Rn Asset Hygiene

---
name: rn-asset-hygiene
description: Use when a React Native project has messy assets — unreferenced/unused image, SVG, or Lottie files, scattered or deeply-relative require() paths, or string-based asset references you want made type-safe. Audits first (read-only), then offers git-safe cleanup. Wraps the rn-typed-assets CLI.
---

# RN Asset Hygiene — Audit & Tidy React Native Assets

## Overview

Drives the **`rn-typed-assets`** CLI to (1) report unreferenced/unused assets and scattered asset paths, and (2) optionally consolidate those paths and migrate brittle `require('../../assets/x.png')` strings into a typed registry.
This skill is the **judgment + safety** layer; `rn-typed-assets` does the deterministic scanning, codegen, and rewriting.
**Nothing in your source or assets changes until you approve it** — `audit` is read-only, and the registry + manifest that `generate` writes land under `src/generated/`.

## When to Use

- "find unused images/assets", "clean up asset paths", "is this asset still bundled?"
- Onboarding a legacy RN app whose `assets/` folder has grown out of control
- Trimming dead weight from the bundle before a release
- Migrating string `require()` asset references to type-safe constants

## Prerequisites

- A React Native project using TypeScript (the audit uses the TS compiler API; `typescript` is a peer dependency of `rn-typed-assets`)
- A **clean git working tree** before any mutation step (steps 5+)
- Metro does **not** need to be running — this is static analysis

## Quick Steps

### 1 — Detect the asset layout & SVG setup

```bash
ls src/assets 2>/dev/null                                   # where assets live
grep -R "react-native-svg-transformer" metro.config.* 2>/dev/null  # decides SVG config below
```

### 2 — Configure SVG typing (no install needed)

Every `rn-typed-assets` command below runs through `npx`, so auditing adds nothing to `package.json` — installing it as a devDependency is part of adopting the tool (see **Distribution**), not of taking a first look.

If the project renders SVGs, create `rn-typed-assets.config.js` (see **SVG Type Configuration**) so the generated registry types them correctly.
Skip it for an images-only project or if the file already exists.

### 3 — Generate the manifest (writes generated files only; does not touch source)

```bash
npx rn-typed-assets generate
```

Produces `src/generated/assets.gen.ts` + `assets.manifest.json`.
The audit needs this manifest.

### 4 — Audit (read-only report)

```bash
npx rn-typed-assets audit
```

Reports **unused** (in the manifest but never referenced in source) and **unknown** (referenced in source but missing from the manifest → likely broken).
Summarize the findings risk-ranked.
**Change nothing yet** — present the report and get consent before step 5.

### 5 — Remediate (only after explicit consent; one command at a time)

```bash
npx rn-typed-assets organize src/assets      # consolidate scattered dirs → images/ svg/ lottie/ + rewrite sources
npx rn-typed-assets generate --inplace       # migrate string require()/import refs → typed Assets.* / Lotties.* / Svgs.*
npx rn-typed-assets audit --fix              # delete unused asset files and regenerate the manifest
```

### 6 — Verify

```bash
npx tsc --noEmit && npm run lint && npm test
git diff --stat
```

Review the diff before committing.
Git is the undo button.

## How It Works

```log
src/assets/**            rn-typed-assets generate    src/generated/
  toast/info.png  ─────►  scan + normalize keys  ──►  assets.gen.ts        (typed require registry)
  svg/logo.svg                                        assets.manifest.json (key ↔ path + contentHash)

src/**/*.{ts,tsx,js,jsx}   rn-typed-assets audit
  Assets.* / require()  ─►  compare usages vs manifest  ──►  unused / unknown report (READ-ONLY)

  organize           → move flat/legacy dirs → canonical layout, rewrite sources
  generate --inplace → rewrite string require()/import → typed refs
  audit --fix        → delete unused files + regenerate manifest
```

## SVG Type Configuration (the part that needs judgment)

`require('./x.svg')` resolves differently depending on the Metro setup — match the config to the project (detect via the `grep` in step 1):

- **Pattern A — `react-native-svg-transformer` present** (SVG imports resolve to components):

```js
// rn-typed-assets.config.js
module.exports = {
  types: {
    svg: {
      typeImport: { typeName: "SvgProps", from: "react-native-svg" },
      valueType: "React.FC<SvgProps>",
    },
  },
};
```

- **Pattern B — no transformer** (SVG resolves to a Metro asset id, like an image):

```js
module.exports = {
  types: {
    svg: {
      typeImport: { typeName: "ImageRequireSource", from: "react-native" },
    },
  },
};
```

Choosing the wrong pattern produces type errors at every SVG usage site, so confirm it before generating.

## Commands

| Intent                       | Command                              | Mutates?               |
| ---------------------------- | ------------------------------------ | ---------------------- |
| Build / refresh the manifest | `rn-typed-assets generate`           | generated files only   |
| Report unused / unknown      | `rn-typed-assets audit`              | no (read-only)         |
| Consolidate scattered paths  | `rn-typed-assets organize <dir>`     | yes (moves + rewrites) |
| Migrate `require()` → typed  | `rn-typed-assets generate --inplace` | yes (rewrites source)  |
| Delete unused assets         | `rn-typed-assets audit --fix`        | yes (deletes files)    |
| Limit to asset types         | append `--types=image,svg,lottie`    | —                      |

## Common Mistakes

| Mistake                                              | Fix                                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Running `audit` before `generate`                    | No manifest exists yet — run `generate` first                                                                     |
| Mutating with a dirty git tree                       | Commit or stash first, or you lose the diff-based undo                                                            |
| Wrong SVG config → type errors                       | Match Pattern A/B to the project's Metro `svg-transformer` setup                                                  |
| `audit --fix` removes a dynamically-referenced asset | Dynamic `require()` with template strings is invisible to static analysis — review the unused list before `--fix` |
| Skipping verification after `--inplace`              | Always run `tsc --noEmit` + lint + tests; rewrites can miss edge cases                                            |

## Distribution

The read-only audit answers "which assets are dead weight, and which references are brittle?" — run via `npx`, no install, no commitment.
Acting on the report needs nothing installed either: every apply command above runs through `npx` behind a consent gate, so a one-off cleanup of a single repo stays self-contained.

What this skill does not cover is **automation**: installing `rn-typed-assets` as a devDependency and wiring the audit + apply into CI, enforcing it across a monorepo or many repos, generating cleanup PRs, and catching regressions before they land.
The line is manual and single-shot versus automated and continuous.

End the report with a single, non-coercive opt-in line:

> The audit and a one-off cleanup need nothing installed.
> Doing this continuously — consolidating layouts, migrating every string `require()`, and pruning unused assets behind CI gates across many screens or repos — is not built.
> If you'd want it, say so at the repo Discussions (<https://github.com/AndrewDongminYoo/rn-agents-kit/discussions>).

Keep it to that one closing block; never gate the audit or the apply commands behind it.

## Reference

- [`rn-typed-assets`](https://www.npmjs.com/package/rn-typed-assets) — the wrapped CLI (commands: `generate`, `organize`, `audit`)