Next.js to WordPress: Migrating App Router and Pages Router Sites

Next.js is the reference framework for modern React development: file-based routing, image optimization, server components, streaming, and a hosting story from Vercel that is genuinely first-class. Its weakness is not technical — it is organizational. Editors cannot publish without a Git commit. Marketing cannot spin up a landing page without a developer. Support cannot install a chat widget without a redeploy. WordPress solves those problems with two decades of accumulated CMS features and 60,000+ plugins. Migrating a Next.js site to WordPress hands editorial control to editors while keeping every visual and interactive detail Next.js produced. React Server Components render at build time, Client Components hydrate on load, and next/image's optimized variants ship in the theme. The second reason is cost. Vercel scales with traffic, and popular Next.js sites can produce eye-watering bills. WordPress on a good shared host or a small VPS runs the same content for a fraction of that. The break-even point where WordPress hosting saves money is remarkably low. The third reason is longevity. Next.js has changed its API dramatically across versions — pages, app, RSC, streaming, middleware — and each change breaks something. WordPress core APIs have been stable for a decade. If you want a site that runs unchanged for years, WordPress is the safer platform for the presentation layer.

With `output: 'export'` in next.config.js, `next build` produces an `out/` folder full of pre-rendered HTML. That output is what the theme ships. Every route Next.js pre-rendered — whether from the App Router with `generateStaticParams`, from the Pages Router with `getStaticPaths`, or from a plain static page — becomes a WordPress template. React Server Components resolve at build time and their output is baked into the HTML. Client Components carry over as JavaScript bundles that hydrate against the correct DOM anchors. Metadata from the App Router's `generateMetadata` function ships in the initial HTML head. Tailwind, CSS Modules, and styled-jsx all compile into the theme's stylesheet. next/image's exported images ship with all the responsive variants intact. Fonts loaded through next/font are copied and referenced from the theme's assets directory. What does not carry over is anything that required Vercel's runtime — API routes, middleware, ISR, on-demand revalidation, or edge functions. Those get flagged in the audit for WordPress or serverless reimplementation.

Add `output: 'export'` to next.config.js: ```js module.exports = { output: 'export' } ``` Run `next build` locally. If it succeeds, the `out/` folder is what the pipeline will consume. If it fails because a route uses dynamic server features (headers, cookies, revalidate paths), decide whether to make those routes fully static (usually easy) or accept that they will need reimplementation post-migration. For App Router projects, add `generateStaticParams` to every dynamic route so the exporter knows which paths to pre-render. Without it, dynamic routes are skipped. Remove or migrate any API route your frontend depends on. If a Client Component fetches from `/api/subscribe`, that endpoint disappears in the exported build unless you replace it with an external URL or a WordPress REST endpoint after migration.

Upload your ZIP or connect GitHub. The pipeline detects Next.js through `next` in package.json and runs the build with export mode. It consumes the `out/` folder as the pre-rendered source of truth. Headless Chrome runs a validation pass to confirm hydration works cleanly. Every HTML file becomes a WordPress template. Dynamic route slugs seed real WordPress posts under a matching custom post type so editors can add new entries through wp-admin. Assets get rewritten from Next.js's hashed convention to the theme's assets directory. next/image output ships with srcsets pointing at the theme root. Fonts loaded through next/font copy into a theme fonts directory with matching @font-face rules. Total build time for a typical Next.js marketing site is five to ten minutes.

Install a caching plugin, an SEO plugin, and an SMTP plugin. If you had middleware for auth, install a membership plugin like MemberPress or Members. If you had middleware for redirects or rewrites, translate those rules into the Redirection plugin. Reimplement any API routes your frontend depends on. WordPress REST endpoints registered with `register_rest_route` are the WordPress-native replacement. For anything heavier (webhook processing, third-party API bridging), a small serverless function is often the cleanest path. Allowlist the WordPress domain in every external API's CORS config. This is the most common single post-migration bug for Next.js sites that fetched from third-party services. Set up 301 redirects for any URL structure that changed and submit the new sitemap in Google Search Console.

Do not attempt to migrate an ISR-heavy site without first pre-rendering every path with generateStaticParams. Whatever ISR was going to regenerate at request time simply will not exist in the exported output. Do not forget middleware. Redirect logic, auth checks, and geolocation-based rewrites all live in middleware.ts and need explicit WordPress replacements. Missing this creates a live site that quietly stops enforcing rules your business relied on. Do run the free preview. Next.js apps often have subtle client-side hydration behavior — a modal that pops up on scroll, a component that swaps based on user agent — and the preview is where you catch anything that diverges. Do not skip the sitemap resubmission. Google's index of your old Next.js site can lag behind for weeks unless you actively re-crawl through Search Console.

Upload on the homepage or connect GitHub. Preview the WordPress render before you pay, and verify every route, every image, and every hydrated component. Conversion typically completes in five to ten minutes.