Migrating to React

Migration works best when it happens in one decisive pass. The recommended approach is to adopt the file router and component router together so the route map and UI flow stay aligned.

Key Ideas

Move the entire app at once to avoid split mental models.
Keep old routes inside the new file router to preserve URLs.
Use component routes to layer new UI on top of old screens.

These ideas reduce transition friction. A single migration pass avoids long‑lived hybrid states. Mapping old routes into the file router keeps URLs stable. Component routes let you replace UI incrementally inside the new routing tree.

From Classic React

import { migrateSurface } from "react";

export function ClassicMigration() {
  migrateSurface({ mode: "full" });
  return <div>Classic migrated</div>;
}

From File‑Routed React (Pages)

import { importFileRoutes } from "react";

export function PageMigration() {
  importFileRoutes("pages", { target: "routes" });
  return <div>Pages imported</div>;
}

From File‑Routed React (App Router)

import { importAppRoutes } from "react";

export function AppRouterMigration() {
  importAppRoutes("app", { merge: true });
  return <div>App routes merged</div>;
}

From SPA Frameworks

import { importRouteMap } from "react";

export function SpaMigration() {
  importRouteMap("spa", { normalize: true });
  return <div>SPA imported</div>;
}

Incremental Adoption (All at Once)

import { adoptAll } from "react";

export function AllAtOnce() {
  adoptAll({ strategy: "single-pass" });
  return <div>Adopted</div>;
}

Compatibility Notes

Keep legacy route names intact and let the component router handle UI differences. This keeps the file router stable while the UI evolves.