Moving from WordPress to Next.js: a migration guide for Persian websites

WordPress still runs a large share of the Persian web, from small company sites to large publishers. It got there for good reasons, but many of these sites score badly on Core Web Vitals because of the theme and page builder, not the content. This is the staged path I use when a client wants Next.js without losing search traffic.

Why the question comes up so often

• WordPress dominates the Persian web, so most businesses already have years of URLs, backlinks and content they refuse to lose.
• Page builders like WPBakery, Elementor and Divi ship large CSS and JavaScript bundles, jQuery and enormous DOM trees. That is what kills LCP and INP, not the images or the hosting.
• Persian plugins for forms, sliders, SEO and translation each add weight, and each is a maintenance and security risk.
• The owner wants to edit content without touching code, and that need survives the migration.

Stage one: audit and baseline

Record the numbers before changing anything, so you can prove the migration worked. Crawl the site and export every indexed URL with its status code, title and canonical. Pull a year of Search Console data and note the top landing pages. Run Lighthouse on a few representative templates with a mobile profile and save the LCP, INP and CLS values. Check the analytics setup, because that is what breaks silently in every migration.

Stage two: get the content out

The REST API is the clean route for standard content: each post type is an endpoint, results are paginated, so script it and follow pages until you have everything. Watch for custom post types and advanced custom fields, since the default endpoint does not return custom fields and you must register them first. For a large site a WP-CLI export to JSON gives you the whole database in one file. Export media separately, keeping original filenames.

Stage three: choose the content architecture

You have two honest options. Keep WordPress as a headless CMS and fetch content at build or request time: your client keeps the editor they know, you get the Next.js frontend, and you accept a moving target. Or import everything into markdown, MDX or a headless CMS and generate static pages, which is fastest when content changes only a few times a week. Most of my clients end up with static content plus a small editing tool for the pages that genuinely change.

Stage four: routes, slugs and redirects

This is where migrations are won or lost. Map every old URL to a new one and keep the path structure identical so the work is mechanical. If you cannot preserve a URL, 301 it to the closest equivalent, never to the homepage. Keep Persian and Arabic slugs exactly as they were, unchanged and un-normalised, because altering them breaks links and makes the site look new to search engines. Do not forget pagination, archives, tag pages, feeds and attachment pages, all of which are usually indexed. Generate the new sitemap.

Stage five: build it fast

Use static generation by default, adding revalidation only where content changes daily: the App Router with static rendering, plus incremental revalidation for pages like a news index. Serve images through the framework image component, sized per breakpoint, in modern formats. Set language and direction on the document element with `lang="fa"` and `dir="rtl"`, and write CSS with logical properties such as `margin-inline-start` instead of left and right, so one stylesheet works both ways.

Persian typography, properly

Do not reach for the Google Fonts loader. Google Fonts is filtered on most Iranian networks, so a font fetched from a Google domain fails or falls back to a system font and flashes. Download a variable Persian font such as Vazirmatn, self host it, and register it with `next/font/local` so Next.js handles the preload and size adjust. One file, two or three weights, `font-display: swap`, and correct line height. Check Persian digits and calendar dates before launch.

The gotchas

• Media URLs. Copy uploads to the new host or object storage, keep filenames identical, and fix hardcoded references in old posts. Stale image URLs cause mixed content warnings.
• Comment forms. Plugin based comments rarely survive. Decide early whether you keep comments, and if you do, plan a simple form plus moderation rather than porting the old system.
• Analytics. Google services are unreliable from inside Iran. Confirm your provider loads for your visitors, or self host a first party cookieless tool so you do not lose history and restart from zero.
• Search. The WordPress search endpoint will not exist. If the site relied on it, add a real index or accept site search.
• Mixed content and plain http URLs inside old content, plus inline styles and scripts nobody audited.
• Testing every redirect with curl, then a final Lighthouse run on the templates you measured at the start.

What success looks like

Compare before and after on identical pages. On the sites I have moved, LCP typically drops from four or five seconds to under two, and INP improves even more because the page builder is gone. Traffic should be flat within a few weeks once redirects settle, and often grows because of the speed. Migrate one template at a time.

Key takeaways

• Baseline before touching anything: export every indexed URL, a year of Search Console data, and LCP, INP and CLS per template.
• Page builders are what kill LCP and INP here, not images or hosting. Removing the builder does most of the work.
• Map every old URL and keep the path structure identical. Redirect to the closest equivalent, never to the homepage.
• Keep Persian and Arabic slugs unchanged and un-normalised, because normalising them breaks links and search equity.
• Use static generation by default, and add incremental revalidation only where content changes daily.

FAQ

Q: Is migrating to Next.js worth it? A: When Core Web Vitals are bad because of the theme and page builder rather than the content, and the owner wants speed without losing years of URLs and backlinks. LCP typically drops from four or five seconds to under two.

Q: Should I keep WordPress as a CMS? A: Keep it headless and fetch content at build or request time, or import everything into markdown, MDX or a headless CMS and generate static pages. Most clients end up with static content plus a small editor.