Headless WordPress setup guide

Headless WordPress keeps the WordPress admin and database as the source of truth for content, but replaces the theme entirely with a separate front end. Instead of PHP templates rendering the page, an API delivers the content and a static site generator or a JavaScript framework renders it. Editors keep the dashboard they know, while the public site runs on a faster, decoupled layer.

Headless basics

In a traditional install, WordPress both stores the content and renders it. In a headless setup, WordPress becomes a content backend that exposes data over the WordPress REST API. A separate front end, such as a static site build that runs a build-time fetch, asks for that content through an endpoint and renders the pages from the returned JSON. Public visitors never hit wp-login.php or the admin at all.

How it connects

A content type like posts maps to a REST route. In a fully default install the posts endpoint already responds at /wp-json/wp/v2/posts. You can extend this with the REST API's register_rest_route for custom post types, and output custom metadata so the front end has what it needs in one call:

function csmbac_register_featured_fields() {
    register_rest_field(
        'post',
        'featured_meta',
        array(
            'get_callback' => function ( $post ) {
                return get_post_meta( $post['id'], '_featured', true );
            },
        )
    );
}
add_action( 'rest_api_init', 'csmbac_register_featured_fields' );

At build or request time the front end fetches the list:

const res = await fetch( 'https://wp.example.com/wp-json/wp/v2/posts?per_page=20' );
const posts = await res.json();

A static site generator performs this fetch during the build so the published HTML is plain files; a framework server can fetch at request time so edits appear after a deploy. Either way the REST API is the only WordPress communication channel.

Trade-offs to weigh

The big wins are a fast front end, full control of markup, and no PHP rendering on the request path. The costs are real. The REST API returns a superset of data, so payloads and the number of requests can grow. Search, pagination, and menus no longer come from ready-made PHP functions, so the front end must implement them. Preview and draft editing in WordPress need the front end to be able to render unpublished states. And the deploy adds a build step.

Headless is the right fit when a team already uses a static or framework toolchain and can sustain the extra integration work. For a marketing site run through the dashboard with a standard theme, a traditional install with caching is simpler and faster to operate. Do not adopt headless purely to gain speed; caching a normal front end usually closes most of that gap with far less complexity.

When it adds real value

Decoupled WordPress shines when the public output is interactive, needs a custom component library, shares content across a site and an app, or is compiled ahead of time for resilience. If those describe your project, prototype the REST endpoints first and confirm the payloads and request pattern work before committing the whole front end.

Foundation to stand on

Headless builds on the WordPress REST API, so read that guide before you wire custom routes. Because the front end is generated output in a decoupled build, the caching and performance settings guides cover keeping the rendered side fast.