{"slug":"migrate-nextjs","title":"migrate-nextjs","summary":"Migrate a Next.js app to pracht: App or Pages Router pages, layouts, middleware, API routes, data fetching, and metadata — plus React→Preact, `className`→`class`, server components→loaders, and manifest wiring. Use for \"migrate from next\", \"convert next.js app\", \"port from next t","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-19T21:17:25.848067Z","repo":{"url":"https://github.com/JoviDeCroock/pracht","stars":99,"forks":5,"license":"MIT","updatedAt":"2026-10-19T16:43:31Z"},"bodyHtml":"
\n

name: migrate-nextjs\nversion: 1.8.1\ndescription: |\nMigrate a Next.js app to pracht: App or Pages Router pages, layouts, middleware,\nAPI routes, data fetching, and metadata — plus React→Preact, className→class,\nserver components→loaders, and manifest wiring.\nUse for \"migrate from next\", \"convert next.js app\", \"port from next to pracht\",\n\"nextjs migration\", \"switch from next\".\nallowed-tools:

\n\n
\n

Migrate Next.js to Pracht

\n

Migrate in phases: setup → shells → routes → client components → API →\nmiddleware → manifest → patterns → cleanup. Read each Next.js source file\nbefore converting it; never infer from the filename. Prefer the simplest\npracht equivalent, and when a Next.js feature has no equivalent, say so and\npropose an alternative instead of inventing one.

\n

With the Pracht MCP server, prefer its generate/inspect/doctor/verify tools;\ninspect_build needs a prior pracht build.

\n

Step 0: Assess the source

\n

Read next.config.* and package.json (React/Next versions, deps), then map\nthe tree: app/ (App Router), pages/ (Pages Router), middleware.ts,\napp/api/ or pages/api/. Note which patterns are in use — \"use client\",\nasync server components, generateStaticParams, generateMetadata/metadata,\n\"use server\" actions — and the third-party integrations (auth, CMS, DB,\nanalytics). Confirm scope with the user if the app has more than ~20 routes.

\n

Agent tools alone do not require a router migration; use the standalone host:\nhttps://pracht.resynapse.dev/docs/standalone-capabilities.

\n

Fast path: Pages Router

\n

pagesDir makes a pages-router source near-drop-in — Phase 7 is then\nautomatic:

\n
    \n
  1. pracht({ pagesDir: \"/src/pages\" }) in vite.config.ts; copy pages/ to\nsrc/pages/.
    2. \n
  2. _app.tsx → pracht shell shape (Shell export taking children). A\nsubdirectory _app scopes a shell to that subtree (blog/_app.tsx →\n\"pages:blog\"), where App Router layout.tsx lands — but shells replace\nrather than nest, so it repeats the chrome, head(), and headers() it\nneeds.
    3. \n
  3. getServerSideProps/getStaticProps → loader export.
    4. \n
  4. export const RENDER_MODE = \"ssg\" on static pages (\"ssr\" is the\ndefault). For time-revalidated pages export RENDER_MODE = \"isg\" plus a\npositive integer REVALIDATE in seconds; webhook policies require ejecting\nto a manifest.
    5. \n
  5. middleware.ts → a root-level src/pages/_middleware.ts exporting a\nMiddlewareFn (Phase 6). It runs on every page route; API routes are not\nwrapped. Move config.matcher checks into the body and compare\nstripBase(url.pathname). A nested _middleware, a _middleware/\ndirectory, and a missing export are build/doctor/verify errors.
    6. \n
  6. Other _-prefixed files and directories are reserved: pracht ignores the\nsubtree. Capabilities live in src/capabilities/ (auto-discovered,\nself-named); agents / constraints in src/pages/_app.config.ts.
    7. \n
  7. Run the dev server, iterate, and optionally eject later with\ngenerateRoutesFile.
    8. \n
\n

Concept mapping

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Next.jsPrachtNotes
pages/ directorypagesDir plugin optionAuto-discovers routes from the file system
app/page.tsxsrc/routes/*.tsx + route() in manifestFile is a module; wiring is explicit
app/layout.tsxsrc/shells/*.tsx + shells in defineApp (pages: _app.tsx per directory)Named shells; a directory _app replaces its parent. Layout data: shell loader + useShellData()
app/loading.tsxLoading export on the shellSSR placeholder for SPA routes until the client router takes over
app/error.tsxErrorBoundary export in route moduleSame concept, different wiring
app/not-found.tsxnotFound: in defineApp (or pages/404.tsx in pagesDir mode)Not a route — never matches a URL, so it cannot shadow static assets
middleware.tssrc/middleware/*.ts + middleware in defineApp (or src/pages/_middleware.ts in pagesDir mode)Named, applied per route/group; the pages-mode file runs on every page route
app/api/*/route.tssrc/api/*.ts with GET/POST exportsAuto-discovered, no manifest entry
generateStaticParamsgetStaticPaths() exportReturns RouteParams[] of param objects
generateMetadatahead() exportReturns { title, meta }
Server Componentsloader() exportData fetching moves to the loader; the component is a Preact component
\"use server\" actionsAPI routes + <Form> / fetchMutations move to src/api/*; return Response objects
\"use client\" (few, mostly-server app)hydration: \"islands\" + src/islands/Only islands ship JS; see Phase 4
revalidatePath / res.revalidate()webhookRevalidate() + POST /__pracht/revalidateOn-demand ISG; combinable with timeRevalidate(seconds)
useRouter() (next/navigation)useNavigate()Takes a path, or { route: \"id\" } after pracht typegen
useSearchParams()useSearchParams()Read-only; set with useSetSearchParams(). SSG gets the browser query after hydration. For typed values export a search schema and read args.search / useSearch()
useParams()useParams()Direct equivalent; also params in loader args
next/link <Link><Link route=\"...\" params={{…}}> or plain <a>Prefer typed <Link> after pracht typegen; the router intercepts same-origin anchors
next/link prefetch={false}<Link prefetch=\"none\">Default \"intent\" (hover/focus); also \"viewport\", \"render\"
useLinkStatus() / pending UIuseNavigation(){ state, location, formData } — progress bars, optimistic UI
next/image<Image> from @pracht/imageResponsive srcsets; Node, Cloudflare, Vercel, or passthrough loaders
next/head or Metadata APIhead() export on route/shellPer-route and per-shell head merging
next/script <Script><Script> from @pracht/corebeforeHydration (≈ beforeInteractive), afterHydration (≈ afterInteractive, default), idle (≈ lazyOnload), visible
cookies() / headers()request.headers in loader/middleware/API argsNo separate API — read the standard Request
classNameclassPreact uses the class attribute
react / react-dom importspreact/hooks, preact/compatSame hook APIs
import React from \"react\"RemoveThe Vite plugin handles JSX
\n

Scroll restoration on back/forward works out of the box. <Link> also takes\npreserveScroll (skip the scroll-to-top reset) and viewTransition (wrap the\nnavigation in document.startViewTransition() where supported).

\n

Phase 1: Project setup

\n

Create src/routes.ts (manifest), src/routes/, src/shells/,\nsrc/middleware/, src/api/, and a vite.config.ts whose plugins array\ncontains pracht() from @pracht/vite-plugin. Then:

\n\n

Phase 2: Layouts → shells

\n
import type { ShellProps } from \"@pracht/core\";\n\nexport function Shell({ children }: ShellProps) {\n  return <div class=\"root\"><main>{children}</main></div>;\n}\n\nexport function head() {\n  return { title: \"My App\" };\n}\n
\n

Shells must NOT render <html>, <head>, or <body> — the framework owns\nthe document, so move anything from RootLayout's document tags into head().\nRegister as defineApp({ shells: { main: \"./shells/main.tsx\" } }).

\n

Phase 3: Pages → route modules

\n

An async page that fetches and exports generateMetadata becomes three\nexports — the fetch moves to loader, the metadata to head, the JSX stays\nin the default export:

\n
import type { LoaderArgs, RouteComponentProps } from \"@pracht/core\";\n\nexport async function loader(_args: LoaderArgs) {\n  const res = await fetch(\"https://api.example.com/data\");\n  return res.json();\n}\n\nexport function head({ data }: { data: Awaited<ReturnType<typeof loader>> }) {\n  return { title: data.title };\n}\n\nexport default function Page({ data }: RouteComponentProps<typeof loader>) {\n  return <div class=\"page\">{data.title}</div>;\n}\n
\n

Components are never async — data arrives as the data prop.

\n

Phase 4: Client components

\n

Drop the \"use client\" directive (pracht has no such concept), and repoint\nimports: react → preact/hooks for hooks, react/react-dom →\npreact/compat for everything else. The component body is otherwise unchanged.

\n

Islands: if the source is mostly server components with a handful of\n\"use client\" leaves, do not silently regress those pages to full-page\nhydration. Set hydration: \"islands\" on the route (or\nexport const HYDRATION = \"islands\" in pages mode) and move the interactive\ncomponents into src/islands/ — the rest renders as inert HTML.

\n

Phase 5: API routes

\n

app/api/users/route.ts → src/api/users.ts, dynamic segments included\n(app/api/users/[id]/route.ts → src/api/users/[id].ts). Handlers take\nApiRouteArgs and use web standards throughout:

\n
import type { ApiRouteArgs } from \"@pracht/core\";\n\nexport async function GET({ request }: ApiRouteArgs) {\n  return Response.json(await getUsers());\n}\n
\n

NextRequest → the standard Request from ApiRouteArgs;\nNextResponse.json() → Response.json(). No manifest wiring — API routes are\nauto-discovered.

\n

Phase 6: Middleware

\n
import { redirect, type MiddlewareFn } from \"@pracht/core\";\n\nexport const middleware: MiddlewareFn = async ({ request }, next) => {\n  const session = request.headers.get(\"cookie\")?.includes(\"session\");\n  if (!session) return redirect(\"/login\", { request });\n  return next();\n};\n
\n

NextResponse.redirect() → return redirect(\"/path\", { request });\nNextResponse.next() → return next(). Path matching moves out of\nconfig.matcher and into manifest assignment:\ngroup({ middleware: [\"auth\"] }, [route(\"/dashboard\", …)]). Pracht middleware\nis wrap-around (Hono/Koa/Astro shape), so you can await next() and observe\nthe response — useful for tracing.

\n

In pagesDir mode the same MiddlewareFn goes in a root-level\nsrc/pages/_middleware.ts, applied to every page route (API routes stay\nunwrapped). Do not migrate a per-request auth matcher onto an ssg/isg page\nand call it protected: that document runs middleware only at\nbuild/revalidation, with a sanitized request. Keep such pages ssr/spa, or\nkeep a separately verified edge gate. Pure static exports have no request\nruntime.

\n

Phase 7: Route manifest

\n

Skip this phase for pagesDir projects. Prefer\npracht generate route --path ... --render ... (plus --shell/--middleware/\n--loader) per page — it creates a wired skeleton and updates\nsrc/routes.ts — then port the Next.js bodies into the generated files.\nHand-write manifest entries only for shapes the generator cannot express.

\n
import { defineApp, group, route } from \"@pracht/core\";\n\nexport const app = defineApp({\n  shells: { main: () => import(\"./shells/main.tsx\") },\n  middleware: { auth: () => import(\"./middleware/auth.ts\") },\n  routes: [\n    group({ shell: \"main\" }, [\n      route(\"/\", () => import(\"./routes/home.tsx\"), { render: \"ssg\" }),\n      route(\"/dashboard\", () => import(\"./routes/dashboard.tsx\"), {\n        render: \"ssr\",\n        middleware: [\"auth\"],\n      }),\n      route(\"/blog/:slug\", () => import(\"./routes/blog-post.tsx\"), { render: \"isg\" }),\n    ]),\n  ],\n  notFound: { component: () => import(\"./routes/not-found.tsx\"), shell: \"main\" },\n});\n
\n

Module references accept () => import(\"./path\") (better IDE navigation) or a\nplain \"./path\" string. Pick render modes from the Next.js original:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Next.js originalRender mode
No data fetching, or generateStaticParams\"ssg\"
cookies(), headers(), per-request data\"ssr\"
revalidate option\"isg\" + timeRevalidate(seconds)
revalidatePath / res.revalidate()\"isg\" + webhookRevalidate(), triggered by POST /__pracht/revalidate
Client-only\"spa\"
\n

Phase 8: Remaining patterns

\n

Links and navigation. After the manifest exists, run pracht typegen and\nswitch known app routes to route ids: <Link route=\"product\" params={{ id }}>\nand navigate({ route: \"dashboard\" }). Plain <a href=\"/about\"> and\nnavigate(\"/dashboard\") keep working for simple, external, or user-provided\nURLs.

\n

Images. <Image> from @pracht/image takes the same\nwidth/height/fill/sizes/quality and priority intent — preserve them.\nPick the loader for the deployment target:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TargetLoader
NodecreateImageHandler() from @pracht/image/node + sharp; set its localOrigin to the same trusted value as nodeAdapter({ canonicalOrigin })
Cloudflare WorkerscloudflareLoader — never bundle the Node handler, sharp does not run in Workers
Vercel EdgevercelLoader, with Vercel's allowed image sizes aligned to the pracht breakpoints
Static hostspassthroughLoader
\n

Static imports and blur placeholders migrate too: import photo from \"./photo.jpg\" → \"./photo.jpg?pracht\", add prachtImage() (from\n@pracht/image/vite) to the Vite plugins, reference the @pracht/image/client\ntypes once in a .d.ts, and keep <Image src={photo} placeholder=\"blur\" />\nas-is — the import supplies width/height/blurDataURL exactly like Next's\nstatic imports, though pracht's blur is CSS-only (no fade, no inline handlers).\nWhere next/image produced files during a static export, use\n?pracht&pracht-static: it emits cached responsive WebP variants and bypasses\nthe runtime loader while keeping plain hydration-free <img> markup. For\nrelative images in Markdown, defineMarkdownCollection() from\n@pracht/markdown applies the same pipeline to ![alt](./photo.jpg). Leave\npublic/ and remote URLs unchanged, and use an absolute Vite base for static\nvariants. See https://pracht.resynapse.dev/docs/images.

\n

Server Actions. A \"use server\" mutation becomes an API route; the\nrevalidatePath half becomes an authenticated webhook call:

\n
import { withBase, type ApiRouteArgs } from \"@pracht/core\";\n\nexport async function POST({ request }: ApiRouteArgs) {\n  const form = await request.formData();\n  await db.insert({ title: form.get(\"title\") });\n  await fetch(new URL(withBase(\"/__pracht/revalidate\"), request.url), {\n    method: \"POST\",\n    headers: {\n      authorization: `Bearer ${process.env.PRACHT_REVALIDATE_TOKEN}`,\n      \"content-type\": \"application/json\",\n    },\n    body: JSON.stringify({ paths: [\"/posts\"] }),\n  });\n  return new Response(null, { status: 303, headers: { location: withBase(\"/posts\") } });\n}\n
\n

That call only does something if /posts is render: \"isg\" and opts in with\nrevalidate: webhookRevalidate() (or [timeRevalidate(seconds), webhookRevalidate()], both imported from @pracht/core), and\nPRACHT_REVALIDATE_TOKEN is set in the runtime environment. If /posts is a\nplain SSR route, drop the call — the redirect re-renders it fresh.

\n

Phase 9: Clean up and verify

\n

Sweep for leftovers: \"use client\"/\"use server\" directives, next/*\nimports, className, react imports, and next.config.*/next-env.d.ts/\n.next/. Run pracht typegen if route ids or paths changed, then pracht dev\nand fix errors iteratively.

\n

Dependency mapping

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Next.js packagePracht equivalent
next@pracht/core + @pracht/cli + @pracht/vite-plugin + a target adapter
next/image@pracht/image
react, react-dompreact
next/font/localImport WOFF2 with ?url&no-inline into defineFont(); register head().fonts, apply font.className/font.style
next/font/googleSelf-host WOFF2 in src/fonts/, then follow next/font/local; pracht never fetches fonts at build time
@next/mdx@mdx-js/rollup (Vite plugin)
next-authDirect integration in middleware/loaders
next/og@vercel/og or a custom solution
\n

Most React libraries work through preact/compat, and the pracht Vite plugin\nalready aliases react/react-dom/react/jsx-runtime for you. Add manual\nresolve.alias entries only when a dependency still fails to resolve — and\nflag those libraries to the user.

\n

$ARGUMENTS

\n","files":[{"path":"SKILL.md","sizeBytes":20106,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-19T21:18:11.214851Z","sha256":"6F21137D03BB186B7F416218174BCD73DC4A23EC097BFF487970023BD5AEF299","sizeBytes":7409},"review":null,"source":{"repositoryUrl":"https://github.com/JoviDeCroock/pracht","path":"skills/migrate-nextjs","license":"MIT","commit":"8bcdd52989de3e97708e7f16221839d6313cfdac","subtreeSha":"44B9B39E45ADC63177206DE13DD99590B83CA919FF6CBDBA526D2EBA1CDF7D61","lastSyncedAt":"2026-10-19T21:17:21.911347Z"},"reviewedAt":"2026-10-19T21:19:40.25662Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/JoviDeCroock/pracht/tree/main/skills/migrate-nextjs"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install jovidecroock-pracht@llmmart"},{"target":"git","command":"git clone https://github.com/JoviDeCroock/pracht.git"}]}