Skip to main content

WordPress to Headless CMS: Migration Playbook

8 min read
Take my WordPress headless

We expose content through the WP REST API, build the Next.js front end and host both.

Step-by-step migration guide from traditional WordPress to a headless architecture with WP REST API, Next.js frontend, and optimized hosting.

Why Migrate to Headless WordPress

Traditional WordPress renders pages server-side through PHP themes. While this works well for simple sites, it creates performance bottlenecks at scale: every page request executes PHP, queries the database, and renders templates. Plugin bloat compounds the problem - each active plugin hooks into the request lifecycle.

Headless WordPress decouples the CMS from the frontend. WordPress becomes a content management API, and a modern frontend framework handles rendering. The result is dramatically faster page loads, better security (the WordPress admin is not publicly accessible), and a superior developer experience.

This playbook covers the complete migration path, based on headless WordPress projects where we handle WordPress performance optimization and infrastructure.

Pre-Migration Assessment

Before migrating, audit your current WordPress installation:

Content Inventory

SELECT post_type, COUNT(*) as count
FROM wp_posts
WHERE post_status = 'publish'
GROUP BY post_type
ORDER BY count DESC;

Document every content type, custom field, taxonomy, and relationship. Custom post types and ACF (Advanced Custom Fields) groups need explicit API exposure.

Plugin Dependency Analysis

Categorize plugins into three groups:

  • Content plugins (ACF, WPML, Yoast): These affect content structure and need API-side equivalents
  • Frontend plugins (Elementor, WPBakery): These become unnecessary in headless mode
  • Backend plugins (WooCommerce, Gravity Forms): These need API endpoints or webhook integration

Setting Up the WordPress API

Exposing Custom Fields

// functions.php
add_action('rest_api_init', function () {
    register_rest_field('post', 'acf_fields', [
        'get_callback' => function ($post) {
            return get_fields($post['id']) ?: [];
        },
        'schema' => [
            'description' => 'ACF fields for this post',
            'type' => 'object',
        ],
    ]);
});

Custom Endpoints for Performance

The default WP REST API returns more data than frontends typically need. Create lean custom endpoints:

add_action('rest_api_init', function () {
    register_rest_route('headless/v1', '/posts', [
        'methods' => 'GET',
        'callback' => function (WP_REST_Request $request) {
            $page = $request->get_param('page') ?: 1;
            $per_page = $request->get_param('per_page') ?: 12;

            $query = new WP_Query([
                'post_type' => 'post',
                'posts_per_page' => $per_page,
                'paged' => $page,
                'post_status' => 'publish',
            ]);

            $posts = array_map(function ($post) {
                return [
                    'id' => $post->ID,
                    'slug' => $post->post_name,
                    'title' => $post->post_title,
                    'excerpt' => wp_trim_words($post->post_content, 30),
                    'date' => $post->post_date,
                    'image' => get_the_post_thumbnail_url($post->ID, 'large'),
                    'categories' => wp_get_post_categories($post->ID, ['fields' => 'names']),
                ];
            }, $query->posts);

            return new WP_REST_Response([
                'posts' => $posts,
                'total' => $query->found_posts,
                'pages' => $query->max_num_pages,
            ]);
        },
        'permission_callback' => '__return_true',
    ]);
});

Building the Next.js Frontend

Data Fetching Layer

// lib/wordpress.ts
const WP_API_URL = process.env.WORDPRESS_API_URL!;

export async function getPosts(page = 1, perPage = 12) {
  const res = await fetch(
    `${WP_API_URL}/headless/v1/posts?page=${page}&per_page=${perPage}`,
    { next: { revalidate: 60 } }
  );
  if (!res.ok) throw new Error("Failed to fetch posts");
  return res.json();
}

export async function getPost(slug: string) {
  const res = await fetch(
    `${WP_API_URL}/headless/v1/posts/${slug}`,
    { next: { revalidate: 300 } }
  );
  if (!res.ok) throw new Error("Post not found");
  return res.json();
}

Incremental Static Regeneration

Use ISR to serve statically generated pages that revalidate in the background:

// app/blog/[slug]/page.tsx
export const revalidate = 300;

export async function generateStaticParams() {
  const { posts } = await getPosts(1, 100);
  return posts.map((post: { slug: string }) => ({ slug: post.slug }));
}

Content Preview System

Editors need to preview unpublished content. Implement a preview mode:

// WordPress: Generate preview links for the headless frontend
add_filter('preview_post_link', function ($link, $post) {
    $frontend_url = 'https://example.com';
    $token = wp_create_nonce('wp_rest');
    return "{$frontend_url}/api/preview?id={$post->ID}&token={$token}";
}, 10, 2);

Infrastructure Setup

The headless architecture requires separate hosting for the WordPress API and the Next.js frontend:

WordPress Backend: Host on a managed server with PHP-FPM, MariaDB, and Redis object cache. Restrict public access to the REST API endpoints only - block wp-admin access to internal IPs.

Next.js Frontend: Deploy on Vercel or a Kubernetes cluster with edge caching. The frontend makes API calls to the WordPress backend during build and on-demand revalidation.

CDN Layer: CloudFront or Cloudflare in front of both services, with aggressive caching for static assets and API responses.

Migration Checklist

  • Export content inventory and validate all custom fields are API-accessible
  • Set up API authentication with application passwords or JWT
  • Build and test all frontend pages against the API
  • Configure webhook-based revalidation for content updates
  • Implement 301 redirects for changed URL structures
  • Run parallel sites for two weeks before DNS cutover
  • Disable the WordPress frontend theme after cutover

Performance Results

Typical improvements after headless migration:

  • TTFB: 800ms to under 100ms
  • LCP: 3.5s to under 1.2s
  • Server costs: 40 percent reduction (WordPress no longer renders pages)
  • Build time: under 3 minutes for 1,000+ pages with ISR

The migration effort pays for itself within months through better Core Web Vitals, higher search rankings, and reduced hosting costs.

Frequently asked questions

How much faster is headless WordPress than a traditional WordPress theme?

Typical results after a headless migration are a Time to First Byte falling from 800ms to under 100ms and Largest Contentful Paint from 3.5s to under 1.2s. Server costs drop by about 40 percent because WordPress no longer renders pages, and ISR keeps build times under 3 minutes for 1,000+ pages. A traditional theme runs PHP, database queries and template rendering on every request, with each active plugin hooking into that lifecycle.

What should I audit before migrating WordPress to headless?

Start with a content inventory, for example a SQL query that counts published rows in wp_posts grouped by post_type. Document every content type, custom field, taxonomy and relationship, because custom post types and ACF field groups need explicit API exposure. Then sort the installed plugins by what happens to them once the theme layer is gone.

Which WordPress plugins still work after a headless migration?

Plugins fall into three groups. Content plugins such as ACF, WPML and Yoast affect the content structure and need API-side equivalents. Frontend builders such as Elementor and WPBakery become unnecessary in headless mode. Backend plugins such as WooCommerce and Gravity Forms need API endpoints or webhook integration to work with the new frontend.

How do I expose ACF fields in the WordPress REST API?

Hook into rest_api_init and call register_rest_field for the post type with a field name such as acf_fields. The get_callback returns the result of get_fields for the post ID, or an empty array when there are none, and the schema declares the field as an object. Custom post types and ACF groups all need this kind of explicit exposure before a headless frontend can read them.

How do I make the WordPress REST API return less data to a headless frontend?

Register a lean custom route such as headless/v1/posts with register_rest_route and build the response from a WP_Query. Return only the fields the frontend uses, such as ID, slug, title, a 30-word excerpt from wp_trim_words, date, the large featured image URL and category names, plus total and pages for pagination. The default WP REST API returns more data than most frontends need.

How do editors preview draft posts in headless WordPress?

Hook the preview_post_link filter so the Preview link points at the headless frontend instead of the WordPress theme. The filter builds a URL to the frontend's /api/preview route carrying the post ID and a token from wp_create_nonce('wp_rest'), which the frontend uses to show the unpublished content.

How should headless WordPress be hosted and secured?

Host the WordPress backend on a managed server with PHP-FPM, MariaDB and a Redis object cache, keep only the REST API endpoints public and restrict wp-admin to internal IPs. The Next.js frontend runs separately on Vercel or a Kubernetes cluster with edge caching. CloudFront or Cloudflare sits in front of both and caches static assets and API responses aggressively. API authentication can use application passwords or JWT.

How long should the old and new sites run in parallel during a headless WordPress migration?

Run the old and new sites side by side for two weeks before the DNS cutover. Before switching, add 301 redirects for any changed URL structures and set up webhook-based revalidation so content updates reach the frontend. Disable the WordPress frontend theme once the cutover is done.

Read how we handle it in DevOps for e-commerce.