rn-new-arch-migration

Category: Tools & Productivity | Uploader: rajivmanivannan | Downloads: 0 | Version: v1.0（Latest）
Use this skill for any React Native New Architecture task — always, without exception.
Changelog: Source: GitHub https://github.com/rajivmanivannan/rn-new-arch-migration-skill
Directory Structure

Current level: Root
📁 eval/
- 📁 fixtures/
  - 📁 project_blocking/
    
    📁 android/
    
    📁 app/
    
    📁 src/
    
    📁 main/
    
    📁 java/
    
    📁 com/
    
    📁 blockingapp/
    
    📄 PaymentModule.java 920 B
    
    📄 PaymentPackage.java 654 B
    
    📁 ios/
    
    📄 HyperpayModule.m 674 B
    
    📁 src/
    
    📄 App.tsx 316 B
    
    📄 package.json 422 B
  - 📁 project_clean/
    
    📄 package.json 443 B
  - 📁 project_interop/
    
    📁 src/
    
    📄 notifications.ts 400 B
    
    📄 package.json 341 B
  - 📁 project_jsonly/
    
    📄 package.json 287 B
- 📁 integration/
  - 📄 __init__.py 0 B
  - 📄 test_integration.py 7.8 KB
- 📁 llm/
  - 📄 __init__.py 0 B
  - 📄 cases.yaml 7.5 KB
  - 📄 run_llm_eval.py 12.5 KB
- 📁 unit/
  - 📄 __init__.py 0 B
  - 📄 test_check_libs.py 13.1 KB
  - 📄 test_generate_pdf_parser.py 10.1 KB
- 📄 requirements.txt 66 B
- 📄 run_all.sh 3.4 KB
📁 references/
- 📄 library-compat.md 6.3 KB
📁 scripts/
- 📄 check_libs.py 32.5 KB
- 📄 generate_pdf.py 35.5 KB
- 📄 known_libs.json 469.3 KB
📄 .gitignore 254 B
📄 LICENSE 1.0 KB
📄 README.md 9.2 KB
📄 requirements.txt 155 B
📄 SKILL.md 15.9 KB
SKILL.md

---
name: rn-new-arch-migration
description: >
  Use this skill for any React Native New Architecture task — always, without exception.
  Triggers: "new architecture", "new arch", "TurboModules", "Fabric renderer", "JSI migration",
  "migrate native modules", "RCTBridgeModule", "enable newArchEnabled", "bridge migration",
  "is my RN app ready", "check native module compatibility", "React Native migration plan",
  "audit my RN project", "NativeModules to TurboModules", "ReactContextBaseJavaModule",
  "react native bridge to JSI", "ViewManager to Fabric", "scan for new arch issues".
  Also trigger on partial requests like "check just my iOS modules", "is react-native-X compatible
  with new arch", or "what do I need to fix before enabling new arch".
  What it does: scans the full project (dependencies, JS/TS source, iOS native, Android native),
  classifies every finding as BLOCKING or INTEROP-OK, calculates a Migration Effort Score,
  and writes a date-stamped MIGRATION_AUDIT_YYYYMMDD.md with a prioritized 4-phase action plan.
  Supports monorepo workspaces and delta/progress mode across audit runs. PDF available on request.
---

# React Native New Architecture Migration Skill

This skill audits a bare React Native project (or monorepo) and produces a date-stamped `MIGRATION_AUDIT_YYYYMMDD.md`. A styled PDF (`MIGRATION_AUDIT_YYYYMMDD.pdf`) is generated on request after the Markdown is delivered. It does NOT rewrite code — it identifies what needs to change, classifies severity, and gives the developer a clear, prioritized plan.

## What this skill covers

- **Dependency audit**: classify npm packages by New Arch compatibility (with live lookup for unknowns)
- **JS/TS source scan**: detect Bridge-era patterns (NativeModules, requireNativeComponent, EventEmitter misuse)
- **iOS native audit**: scan for RCTBridgeModule, RCT_EXPORT_MODULE, RCT_EXPORT_METHOD patterns
- **Android native audit**: scan for ReactContextBaseJavaModule, @ReactMethod, @ReactProp, ReactPackage patterns
- **Interop vs rewrite triage**: distinguish what can run under interop mode vs what must be rewritten
- **Priority score**: calculate a weighted migration effort score per finding
- **Monorepo support**: detect and scan each workspace package independently
- **Delta mode**: diff new findings against a previous audit to show progress
- **Token tracking**: record approximate tokens consumed by the audit session
- **PDF output**: generate a styled PDF on request after the Markdown report is delivered

---

## Step 0 — Project fingerprinting & monorepo detection

### 0a — Detect monorepo

```bash
cat package.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('workspaces','none'))"
ls packages/ apps/ libs/ 2>/dev/null
```

**If monorepo detected:** Collect each workspace package path. For each sub-package containing `react-native` in its dependencies or a `ios/` or `android/` directory, add it to the scan list. Run Steps 1–7 once per package. Produce one combined report with per-package sections (see monorepo structure at end of this file). Label each section clearly.

**If single app:** proceed normally.

### 0b — Fingerprint

Read per package — treat every file as optional and handle gracefully if missing:

```bash
# Safe reads — never fail if file absent
[ -f package.json ]              && cat package.json         || echo "{}"
[ -f app.json ]                  && cat app.json             || echo "{}"
[ -f android/build.gradle ]      && cat android/build.gradle || echo ""
[ -f android/gradle.properties ] && cat android/gradle.properties || echo ""
[ -f ios/Podfile ]               && cat ios/Podfile          || echo ""
[ -f babel.config.js ]           && cat babel.config.js      || echo ""
```

Extract and handle each missing case explicitly:

- **RN version** — read from `react-native` in `package.json` dependencies. If absent, note "RN version not detected" and still run the full audit.
- **Hermes enabled** — check `package.json` android/ios sections and Podfile. If neither present, note "Hermes: Not detected".
- **TypeScript or Flow** — check for `tsconfig.json` or `.flowconfig`. If neither, note "Type system: Not detected".
- **New Arch already enabled** — check `android/gradle.properties` for `newArchEnabled=true` and `ios/Podfile` for `RCT_NEW_ARCH_ENABLED=1`. Default to "Not enabled" if files are absent.
- **iOS layer** — if `ios/` directory does not exist, skip Step 3 entirely and note "No iOS directory found — iOS audit skipped" in the report.
- **Android layer** — if `android/` directory does not exist, skip Step 4 entirely and note "No Android directory found — Android audit skipped" in the report.
- **JS-only library** — if neither `ios/` nor `android/` exists but `package.json` is present, this may be a JS-only package in a monorepo. Run Steps 1–2 only and note the scope in the report.
- **Malformed package.json** — if `package.json` cannot be parsed as valid JSON, abort with a clear message: "Cannot parse package.json — please fix JSON syntax errors before running the audit."

> If RN version < 0.68, prepend a prerequisite block to the report. Still run the full audit.

### 0c — Delta mode detection

```bash
ls MIGRATION_AUDIT_*.md 2>/dev/null | sort | tail -1
```

If a previous audit exists, parse its dependency table and source/native finding tables. Store them as the **baseline**. Record the previous audit date and MES for comparison in Step 7.

---

## Step 1 — Dependency audit

**Run the library checker script first — do not attempt manual lookups.**

```bash
python3 $(find .claude/skills ~/.claude/skills -name check_libs.py 2>/dev/null | head -1) \
  --project-root . \
  --cache-dir .rn-arch-cache
```

This script:
- Checks all deps in **parallel** (10 workers) against a built-in known list + reactnative.directory API + npm registry
- **Auto-detects and silently skips pure-JS packages** (no native code, irrelevant to New Arch)
- **Caches results for 7 days** — re-runs on the same project are near-instant
- Flags packages with no release in 2+ years as ❌ Unmaintained automatically
- Outputs `.rn-arch-cache/lib_report.json`

**Read the JSON report** (costs ~150–200 tokens regardless of project size):

```bash
cat .rn-arch-cache/lib_report.json
```

The JSON shape is:
```json
{
  "summary": { "compatible": 20, "interop": 2, "blocking": 1, "unknown": 3 },
  "pure_js_skipped": 6,
  "libraries": [
    {
      "package": "react-native-snap-carousel",
      "version": "^3.9.1",
      "status": "blocking",
      "notes": "Unmaintained — replace with react-native-reanimated-carousel",
      "replacement": "react-native-reanimated-carousel"
    }
  ]
}
```

Use this JSON directly to write the dependency audit tables in the report. Do not re-fetch, re-reason, or re-classify anything the script has already resolved.

**Status values from the script:**
| Value | Label | Meaning |
|-------|-------|---------|
| `compatible` | ✅ Compatible | Confirmed New Arch support |
| `interop` | ⚠️ Interop OK | Works via interop layer — deferred, not permanent |
| `blocking` | ❌ Blocking | Must replace or upgrade before enabling New Arch |
| `unknown` | ❓ Unknown | Script could not determine — note the repo URL from `notes` field |

For any remaining `unknown` entries, note them in the report with the repo URL from the `notes` field. Do not attempt further lookups — the script has already exhausted what's automatable.

---

## Step 2 — JS/TS source scan

```bash
grep -rn "NativeModules\." src/ app/ screens/ components/ lib/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | grep -v node_modules | grep -v "__tests__"
grep -rn "requireNativeComponent" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null
grep -rn "NativeEventEmitter\|DeviceEventEmitter.addListener" src/ app/ --include="*.ts" --include="*.tsx" 2>/dev/null
```

| Pattern | Tag | Severity |
|---------|-----|----------|
| `NativeModules.X` (first-party module) | `TURBOMODULE_NEEDED` | BLOCKING |
| `requireNativeComponent(...)` | `FABRIC_NEEDED` | BLOCKING |
| `new NativeEventEmitter(NativeModules.X)` | `EVENT_EMITTER_REVIEW` | INTEROP-OK |
| `DeviceEventEmitter.addListener` for native events | `DEVICE_EVENT_EMITTER` | INTEROP-OK |
| `NativeModules.SettingsManager` / `I18nManager` | `RN_INTERNAL_MODULE` | INTEROP-OK (low severity) |

Don't flag unused imports or test/mock files.

---

## Step 3 — iOS native audit

```bash
# Guard: skip entirely if ios/ does not exist
[ -d ios ] && find ios/ \( -name "*.m" -o -name "*.mm" -o -name "*.swift" \) \
  | grep -v Pods | grep -v build | grep -v DerivedData \
  | xargs grep -ln "RCTBridgeModule\|RCT_EXPORT_MODULE\|RCT_EXPORT_METHOD\|RCTViewManager\|RCT_EXTERN_MODULE" 2>/dev/null \
  || echo "ios/ not found — iOS audit skipped"
```

| Pattern | Tag | Action |
|---------|-----|--------|
| `RCTBridgeModule` protocol | `IOS_BRIDGE_MODULE` | Rewrite as TurboModule + Codegen spec |
| `RCT_EXPORT_MODULE()` / `RCT_EXTERN_MODULE` | `IOS_EXPORT_MODULE` | Replace with TurboModule registration |
| `RCT_EXPORT_METHOD(...)` / `RCT_EXTERN_METHOD` | `IOS_EXPORT_METHOD` | Move to TurboModule interface |
| `RCT_EXPORT_VIEW_PROPERTY` | `IOS_VIEW_PROPERTY` | Move to Fabric ViewComponent |
| `RCTViewManager` subclass | `IOS_VIEW_MANAGER` | Full Fabric rewrite required |
| `.bridge` property access | `IOS_BRIDGE_ACCESS` | Direct bridge coupling — must remove |
| `@objc(ModuleName)` class / `@objc func` in module | `IOS_SWIFT_MODULE` | Requires `RCTTurboModuleHostObject` — flag for manual review |

---

## Step 4 — Android native audit

```bash
# Guard: skip entirely if android/ does not exist
[ -d android/app/src ] && find android/app/src/ \( -name "*.java" -o -name "*.kt" \) \
  | grep -v build \
  | xargs grep -ln "ReactContextBaseJavaModule\|@ReactMethod\|@ReactProp\|ReactPackage\|SimpleViewManager\|ViewGroupManager" 2>/dev/null \
  || echo "android/app/src/ not found — Android audit skipped"
```

| Pattern | Tag | Action |
|---------|-----|--------|
| `ReactContextBaseJavaModule` | `ANDROID_BASE_MODULE` | Rewrite as TurboModule |
| `@ReactMethod` | `ANDROID_REACT_METHOD` | Move to TurboModule interface |
| `@ReactProp` | `ANDROID_REACT_PROP` | Move to Fabric ViewComponent |
| `SimpleViewManager` / `ViewGroupManager` | `ANDROID_VIEW_MANAGER` | Full Fabric rewrite required |
| `ReactPackage` implementation | `ANDROID_REACT_PACKAGE` | Refactor for TurboReactPackage |
| `getReactApplicationContext()` in business logic | `ANDROID_CONTEXT_LEAK` | Potential memory issue — flag |
| `WritableNativeMap` / `WritableNativeArray` | `ANDROID_NATIVE_MAP` | Replace with typed Codegen interfaces |

---

## Step 5 — Interop vs rewrite triage

**BLOCKING (must fix before enabling New Arch):**
- First-party `RCTBridgeModule`, `ReactContextBaseJavaModule`
- First-party `requireNativeComponent`
- `.bridge` property access
- Libraries marked ❌
- First-party `RCTViewManager` / `ViewGroupManager` / `SimpleViewManager`
- First-party `NativeModules.X` calls

**INTEROP-OK (defer until after New Arch is stable):**
- `NativeModules.SettingsManager` / `I18nManager` (RN-internal)
- `NativeEventEmitter` with correct listener methods
- `DeviceEventEmitter` for non-critical events
- Libraries marked ⚠️

---

## Step 6 — Priority scoring

| Finding type | Points |
|---|---|
| ❌ Blocking library | 15 |
| ❓ Unknown library (with native risk) | 5 |
| `IOS_VIEW_MANAGER` or `ANDROID_VIEW_MANAGER` | 20 |
| `IOS_BRIDGE_MODULE` or `ANDROID_BASE_MODULE` | 15 |
| `FABRIC_NEEDED` | 10 |
| `TURBOMODULE_NEEDED` | 8 |
| `IOS_EXPORT_METHOD` or `ANDROID_REACT_METHOD` (per occurrence) | 3 |
| `IOS_SWIFT_MODULE` | 12 |
| `ANDROID_REACT_PACKAGE` | 5 |
| Other patterns | 2 |

**MES ranges:** 0–20 Low · 21–60 Moderate · 61–120 High · 121+ Very High

---

## Step 7 — Delta summary (only if previous audit found)

Compute the diff between previous and current findings:

```
## Progress Summary
Previous audit: MIGRATION_AUDIT_YYYYMMDD.md  (MES: 120)
Current  audit: MIGRATION_AUDIT_YYYYMMDD.md  (MES: 87)

Resolved (8):  ✅ react-native-snap-carousel removed
               ✅ IOS_BRIDGE_MODULE ios/OldModule.m — fixed
               ...
New (2):       🆕 NativeModules.NewFeature in src/feature.ts:42
               ...
Remaining (14): ⏳ IOS_BRIDGE_MODULE ios/Hyperpay.m
                ...

MES delta: −33 points (↓ 27.5%)
```

Place this block immediately after the report header, before the Executive Summary.

---

## Step 8 — Token tracking

At the end of the audit, record approximate token usage in the `## Audit Metadata` section:

```markdown
## Audit Metadata
| Field | Value |
|-------|-------|
| Audit date | YYYY-MM-DD |
| Model | claude-sonnet-4-6 |
| Estimated input tokens | ~X,XXX |
| Estimated output tokens | ~X,XXX |
| Total estimated tokens | ~X,XXX |

> Token counts are approximate. Exact usage is visible in Claude Code session stats (bottom of terminal).
```

To estimate: count the files read (each ~500–2000 tokens depending on size) plus the report output length.

---

## Step 9 — Generate output files

### 9a — Markdown (always)

Write `MIGRATION_AUDIT_YYYYMMDD.md` to the project root using today's date. This is always produced — it is the primary deliverable.

Always append a hidden `<!-- PDF_META ... -->` comment at the very end of the file so the PDF script can parse metadata if requested later. It is invisible in all Markdown renderers.

```markdown
<!-- PDF_META
project: MyApp
rn_version: "0.76.0"
rn_eligible: true
hermes: Enabled
new_arch_enabled: false
mes_score: 105
mes_label: High
audit_date: "2026-03-20"
js_files_scanned: 1182
ios_files_scanned: 6
android_files_scanned: 8
deps_audited: 82
blocking_count: 1
interop_count: 2
compatible_count: 20
unknown_count: 3
model: claude-sonnet-4-6
input_tokens: 12400
output_tokens: 3200
-->
```

### 9b — PDF (on request only)

**Do NOT generate the PDF automatically.** After delivering the Markdown report, ask:

> "The Markdown report is ready. Would you like a PDF version as well?"

Only run the PDF script if the user says yes:

```bash
python3 $(find .claude/skills ~/.claude/skills -name generate_pdf.py 2>/dev/null | head -1) \
  --input ./MIGRATION_AUDIT_YYYYMMDD.md \
  --output ./MIGRATION_AUDIT_YYYYMMDD.pdf
```

If the script errors, note it in the response — the Markdown report is the complete deliverable regardless.

If the user explicitly asked for a PDF upfront (e.g. "generate a PDF audit" or "I want both files"), skip the question and generate both in one go.

---

## Monorepo combined report structure

```markdown
# React Native New Architecture Migration Audit — Monorepo

**Workspace root:** [path]  |  **Packages scanned:** N  |  **Audit date:** YYYY-MM-DD
**Combined MES:** [sum]

## Workspace Summary

| Package | RN Version | MES | Blocking | Interop | Status |
|---------|------------|-----|----------|---------|--------|
| apps/consumer | 0.76.0 | 87 | 3 | 2 | ⚠️ Action needed |
| apps/driver   | 0.74.2 | 22 | 0 | 4 | ✅ Nearly ready  |

---

## Package: apps/consumer
[Full sections 1–6]

---

## Package: apps/driver
[Full sections 1–6]
```

---

## Important reasoning notes

**Interop mode:** Items are "deferred, not resolved." Communicate clearly that the interop layer may be removed in a future RN version.

**Codegen:** Every TurboModule and Fabric component rewrite requires a `.ts` spec file alongside the native implementation.

**Swift TurboModules:** Not a straight port — flag all `IOS_SWIFT_MODULE` for extra manual review.

**Kotlin:** Recommend (not require) Kotlin rewrite alongside Java→TurboModule migration.

**Avoid false positives:** Only flag clear native bridge usage. Exclude unused imports and test files.

---

## Reference files

- `references/library-compat.md` — Offline fallback compat list (~58 packages). Read automatically by `check_libs.py` when `known_libs.json` is missing/empty and network is unavailable. Do not read this manually.
- `scripts/known_libs.json` — Auto-generated from reactnative.directory. Primary library data source.
- `scripts/generate_pdf.py` — PDF generation script. Run in Step 9b.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
rn-new-arch-migration

Directory Structure

SKILL.md

Report

Notice
