Migrate an existing React app

Srijika migrates an existing React application into a different new project. It does not restructure the source in place. Source and target are resolved to canonical paths; equal, nested, overlapping, and symlink-aliased roots are rejected before a target write.

Evidence, not a zero-loss promise

Srijika does not claim that arbitrary React code can be rewritten automatically or that context loss is impossible. Unsupported or ambiguous behavior blocks a slice. Completion requires the source baseline, traceability, architecture, build, typecheck, and tests to pass with no hidden unmapped source item.

Start from the CLI

srijika migrate react \
  --source /absolute/path/old-react-app \
  --target /absolute/path/new-srijika-app

You can also use the creation alias:

srijika create ../new-srijika-app --from ../old-react-app

Preview without creating the target by adding --dry-run. Add --json for automation. Resume and verify the persisted session with:

srijika migrate status --target ../new-srijika-app
srijika migrate parity --target ../new-srijika-app
srijika migrate verify --target ../new-srijika-app
srijika migrate finalize --target ../new-srijika-app

Parity launches engine-owned isolated source/target runtimes. Add --include-install only when dependency downloads are explicitly permitted.

The session lives at <target>/.srijika/migrations/react/session.json. CLI, MCP, VS Code, and Studio all read the same session and call the same migration engine.

Use Codex with MCP

Ask Codex to convert the absolute source path into the absolute target path and explicitly say the source must not change. Codex follows this tool sequence:

1. srijika_create_react_migration
2. srijika_scan_react_migration_source
3. srijika_get_react_migration_plan
4. srijika_review_react_migration_ownership only for a bounded semantic correction
5. srijika_get_react_migration_slice_context
6. srijika_review_react_migration_slice
7. srijika_apply_react_migration_slice
8. srijika_verify_react_migration_slice
9. srijika_get_react_migration_status when resuming
10. srijika_verify_react_migration
11. srijika_finalize_react_migration

Scan, plan, and status support compact pagination with an opaque query-bound cursor and limit (50 rows by default, 200 maximum). Reuse nextCursor unchanged only with the same source snapshot, plan, and optional sliceId; replay against another query fails closed. Review can include expected-hash deletion of obsolete generated starter files. After interruption, status returns any pending apply handle; pass it unchanged as reviewToken.

Slice context is the source reader for MCP-only conversion. Supply the same expected plan/source/target snapshot fields used for ownership review. It returns at most 32 files and 2 MiB per page (8 files and 512 KiB by default), rechecks every file hash against the immutable baseline, includes imports/exports and canonical ownership, keeps environment values secret, and returns binary assets as hashes only. Repeat nextCursor with the same target and sliceId.

Ownership correction is allowed only before the first slice review or apply. Each override names an inventoried source plus a canonical owner kind, name, path, role, and rationale; the request also repeats the exact current plan ID and source and target snapshots. The engine rejects stale state, freehand paths, invalid owner-role pairs, stale source state, duplicates, and late corrections, then returns a new plan ID and recomputed SCC-atomic slices. Use planId, sourceSnapshotSha256, and targetBaselineSha256 from one plan response as expectedPlanId, expectedSourceSnapshotSha256, and expectedTargetSnapshotSha256; never mix values from separate reads.

Create is a target-only preflight/scaffold operation. Scan, plan, and status are read-only. The ownership plan fixes owner IDs, paths, roles, graph components, completion obligations, and bounded adapter planning hints. Review persists the exact payload and returns a token; apply accepts only target plus that token and writes atomically inside the target. Finalize fails closed until every runtime mapping is native and every current gate passes.

Slice verification executes typecheck and build in the target. Global verification executes typecheck, build, and test. The engine creates receipts bound to the current target snapshot; MCP does not accept caller-authored command statuses, receipts, routes, screenshots, evidence paths, or free-form pass claims. When route or visual parity applies, the engine prepares an isolated temporary source copy and the converted target, selects separate loopback ports, derives routes, captures fixed-viewport semantic DOM, redirects, console/page errors, and PNGs, applies fixed thresholds, and persists a source/target-snapshot-bound manifest. Codex supplies only target and optional includeInstall.

Codex inventories routes and layouts, components and typed contracts, hooks, context/state/query behavior, API and authentication boundaries, CSS and assets, forms, environment use, loading/error/responsive states, and tests. It maps one coherent route or dependency slice at a time into canonical Feature, Slot, Part, Shared UI, Shared Widget, or Shared Headless Capability owners.

VS Code workflow

Open Srijika → Migration in the Activity Bar, or run Srijika: Open React Migration Dashboard. Select the read-only source, then choose a new separate target or use the current workspace only when it is an eligible empty/resumable target. The engine rejects in-place conversion, overlap, symlinks, and unrelated files regardless of the selected UI mode.

The dashboard shows the shared inventory, canonical owner tree and roles, ordered slices, applied/verified progress, blockers, and verification status. Refresh sees work performed through CLI, MCP, Studio, or another agent because nothing important is stored only in the webview. The connector card reports local Codex detection and Srijika MCP configuration separately from live MCP authentication, and Copy Codex handoff produces a safe session-aware resume instruction.

Use Full session JSON to inspect the complete uncapped machine-readable inventory and plan behind the compact dashboard.

Interactive architecture graph

Open Architecture Graph renders the persisted plan in a full editor panel: Application → Feature → Slot → Part plus Shared/application/project owners. Clicking an owner expands its modules and lazily loads exact named exports from bounded immutable slice context. Applied UI → Connector → Hook/Store/API nodes, imports, and exports come from bounded read-only inspection of the real converted target; pending obligations stay marked as planned source. Details include roles, paths, canonical targets, imports, exports, and linked evidence.

Ownership edges are gray, same-owner imports blue, Shared imports green, and cross-owner review edges dashed amber. Amber is not silently called a Srijika violation. Red is reserved for engine evidence such as unresolved imports, unsupported findings, unmapped/unowned paths, failed Srijika diagnostics, architecture/target-graph gates, or failed slice commands. Search, violations-only mode, dependency visibility, collapse, zoom, and refresh support both the whole-product overview and one-owner inspection.

To keep the view on the right, enable View → Appearance → Secondary Side Bar, then choose Move View → Secondary Side Bar from the Migration view menu. Without the extension, use the CLI in the integrated terminal or the generated MCP connection.

Desktop Studio workflow

Desktop Studio is also optional. It consumes the same session and migration engine; it is useful for reviewed visual comparisons, not as a second migration source of truth. Code and session evidence remain authoritative.

What verification proves

Before completion Srijika checks:

• the source baseline is unchanged;
• every runtime source item satisfies its canonical native owner and role;
• the target import/dependency graph is closed, with no compatibility mapping, wrapper/re-export, copied legacy subtree, source dependency, or unowned module;
• every resolved UI source has zero Srijika diagnostics;
• strict Feature → Slot → Part → Shared architecture passes;
• build, typecheck, and tests pass; and
• route and representative visual/responsive evidence exists when applicable.

Typecheck, build, and test are always required and must pass when executed by the engine. A target without a declared test script remains blocked; architecture validation is not a test substitute. A source with route files or semanticRoutesPresent requires a fresh engine-owned browser capture; semantic routes implemented inside entry or other files still count. A source with entry, component, style, or asset files requires the same capture at two or more canonical viewports. The default matrix is engine-owned. Finalize rebuilds both isolated runtimes, recaptures, reruns the gates, and revalidates the persisted engine manifest. These conditional gates cannot be skipped, and slice verification also rechecks that the source baseline has not changed.

Browser capture requires Playwright and Chromium. The published MCP package declares Playwright as optional; if Chromium is missing, run npx playwright install chromium. A bundled Codex plugin fails closed when its host cannot resolve Playwright or launch Chromium—caller screenshots never become a substitute.

{
  "target": "/absolute/path/new-srijika"
}

Set includeInstall: true only when dependency downloads are explicitly permitted. URLs, ports, routes, and viewports are not tool inputs.

If any evidence is missing or stale, the session remains incomplete and reports the exact blocker.

For every slice, use the short gate: zero Srijika diagnostics → architecture pass → TypeScript pass → production build pass. Do not start the next slice until all four pass.