Next.js Pages to App Migration skill for Codex

Done well means: the app ships after every migrated route, no URL exists in both routers, each moved page keeps its status codes, metadata, redirects and data freshness, and the pages/ directory shrinks in small reviewable commits instead of one rewrite.

Ground rules

• Migrate incrementally. Both routers run in one app; nothing forces a big bang.
• Never define the same URL in both pages/ and app/; that is a build error. Move a route by creating the app/ version and deleting the pages/ file in the same commit.
• Navigation between a pages/ route and an app/ route is a full page load. Migrate routes that link to each other heavily (a section and its children) together.
• Upgrade Next.js to the target major on the pages router first, ship that, then start moving routes. Mixing a major upgrade with a router migration hides the cause of every regression.
• Keep behavior identical first; refactor to new patterns (streaming, server actions) after the route is on app/.

Workflow

- [ ] 1. Inventory routes and score effort
- [ ] 2. Upgrade Next.js on the pages router and ship
- [ ] 3. Create the root layout from _app and _document
- [ ] 4. Migrate routes, lowest effort first, one PR each (or one section)
- [ ] 5. Move special files (404, 500, _error) last
- [ ] 6. Delete pages/ when only API routes (optional) remain

1. Inventory

Run the bundled script from the skill folder (Node 20+, no dependencies):

node scripts/pages_inventory.mjs <project-root>          # markdown table
node scripts/pages_inventory.mjs <project-root> --json   # for further processing

It lists every pages/ file with its URL, data-fetching functions, next/router and next/head usage, the suggested app/ target and an effort score. It exits 1 if a URL already exists in both routers. Paste the table into the migration issue as the plan.

Also read AGENTS.md, next.config.* (look for i18n, basePath, rewrites, redirects), and the test setup. The pages router i18n config has no app/ equivalent; plan locale routing (step 4) before migrating localized pages.

3. Root layout

// app/layout.tsx
import "./globals.css"; // global CSS imports from _app move here
import { Providers } from "./providers";
import type { Metadata } from "next";

export const metadata: Metadata = {
  title: { default: "Acme", template: "%s | Acme" },
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

// app/providers.tsx
"use client";
export function Providers({ children }: { children: React.ReactNode }) {
  // theme, query client, analytics: whatever _app wrapped around <Component />
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

• _document customizations (lang, body classes, fonts, beforeInteractive scripts) go into the root layout. Fonts: next/font in the layout.
• _app per-page layouts (Component.getLayout) become nested layout.tsx files.
• pages/_app keeps serving the remaining pages/ routes; do not delete it yet.

4. Migrate a route

Lift and shift first: make the app/ page a server component that fetches what getServerSideProps/getStaticProps returned, and render the existing page component (marked "use client" if it uses hooks) with the same props.

// Before: pages/orders/[id].tsx
export const getServerSideProps: GetServerSideProps = async ({ params, req }) => {
  const session = await getSession(req);
  if (!session) return { redirect: { destination: "/login", permanent: false } };
  const order = await getOrder(String(params!.id), session.userId);
  if (!order) return { notFound: true };
  return { props: { order } };
};
export default function OrderPage({ order }: Props) { /* hooks, UI */ }

// After: app/orders/[id]/page.tsx
import { notFound, redirect } from "next/navigation";
import { OrderView } from "./order-view"; // the old component, now "use client"

export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const session = await getSession(); // reads cookies() internally
  if (!session) redirect("/login");
  const { id } = await params;
  const order = await getOrder(id, session.userId);
  if (!order) notFound();
  return <OrderView order={order} />;
}

Mapping table:

pages/	app/
getServerSideProps	async server component; read cookies()/headers() from next/headers
getStaticProps	cached data fetch (fetch with cache: "force-cache", or "use cache" with Cache Components)
revalidate: 60	export const revalidate = 60, or cacheLife under Cache Components
getStaticPaths	generateStaticParams
fallback: false	export const dynamicParams = false (with Cache Components: call notFound())
fallback: "blocking"	default behavior
fallback: true	loading.tsx or <Suspense> around the data
{ notFound: true } / { redirect }	notFound() / redirect() / permanentRedirect()
getInitialProps	server component data fetch; remove it from _app as early as possible
next/head	export const metadata or generateMetadata
useRouter from next/router	useRouter, usePathname, useSearchParams, useParams from next/navigation
router.query	params / searchParams page props, or useParams / useSearchParams
router.events	effect on usePathname() + useSearchParams() changes
router.locale, i18n config	app/[lang]/ segment plus locale detection in proxy.ts (middleware.ts before Next 16)
pages/api/x.ts	may stay; or app/api/x/route.ts with Web Request/Response
pages/404.tsx, pages/500.tsx, _error	app/not-found.tsx, app/global-error.tsx, error.tsx
next/legacy/image	next/image

Shared components used by both routers: import useRouter from next/compat/router; it returns null under app/, so branch on that instead of crashing.

API route conversion (only when you have a reason; pages/api keeps working):

// app/api/users/[id]/route.ts
export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const user = await findUser(id);
  return user ? Response.json(user) : Response.json({ error: "not found" }, { status: 404 });
}

req.query becomes new URL(req.url).searchParams (or request.nextUrl.searchParams with NextRequest); res.status(x).json(y) becomes Response.json(y, { status: x }). Body parser config (export const config = { api: { bodyParser } }) has no equivalent; read the body with req.json(), req.formData() or req.text().

Codemods

npx @next/codemod@latest provides transforms for version upgrades (async request APIs, next/image and others); run it without arguments to choose interactively. It needs network access for npx; in a sandbox without network, ask the user to approve or apply the transform by hand. No codemod converts data-fetching functions; do those manually with the table above.

Gotchas

• getServerSideProps ran per request; a server component with an uncached fetch also does, but a page with no request APIs and only cached fetches becomes static. Check the build route table to confirm the rendering mode did not change by accident.
• Props passed from the server page to the old client component must be serializable. Pages that returned Date via superjson or class instances need explicit mapping.
• SWR or React Query fallback/initialData from getServerSideProps can stay: pass the server-fetched data as initialData to the client component until you refactor.
• next/head tags inside client components are ignored in app/. Move all metadata to metadata/generateMetadata.
• useSearchParams in a statically rendered app/ page must sit inside <Suspense>.
• Middleware matchers written for pages/ URLs may need updates for new route groups and locale segments.
• Analytics page-view tracking hooked to router.events silently stops on migrated routes. Re-implement it before migrating high-traffic pages.

Verification per migrated route

• next build passes and the script reports no conflicts.
• Same HTTP status, <title>, meta description, canonical and robots tags as before (curl -s <url> | grep -E '<title>|canonical|robots' before and after).
• Redirects and 404s behave as before for logged-out users and missing records.
• Links to and from the route work; note which are now hard navigations between routers.
• Existing e2e tests for the route pass unchanged.

Output

Per PR: the inventory rows moved (from the script table), a before/after note on rendering mode, and any behavior intentionally changed. Keep the remaining inventory in the tracking issue up to date.