Is headless WordPress with Next.js right for your site?

You have heard that headless WordPress with Next.js makes a site much faster, or you already have a quote for one. It sounds good, but it is not clear what exactly you are buying, how much harder it will be to run, or whether you need it at all.

This guide explains in plain words how such a site works, what you gain and what you pay for it. Then we go through the cases where headless is worth it and the ones where classic WordPress is the better choice. There is a checklist at the end to help you judge your own case.

What is headless WordPress with Next.js?

Classic WordPress does two jobs at once. In the admin you write the content and upload the images, and the theme turns them into the pages visitors see. Every page view that is not served from the cache goes through PHP and the database.

Headless means "without a head". The head is the public part of the site, and in this approach it is separated from WordPress. Your team keeps writing and editing in the familiar admin, with the editor and the media library. The site visitors see is a separate application built with Next.js, a React framework for building websites and web applications.

The two parts talk through an API, a set of addresses one program uses to read another program's data. WordPress has a built-in REST API that returns posts, pages and media as JSON, a simple text format for data. Another option is WPGraphQL, a free plugin that lets the Next.js site ask WordPress for exactly the fields it needs.

You can see this data on your own site. Open https://primer.bg/wp-json/wp/v2/posts in your browser, replacing primer.bg with your domain. You will see your latest posts as plain data, with no design at all. If you get an error instead, a security plugin is probably restricting access to the REST API.

How Next.js reads posts from WordPress

To make this concrete, here is a short example based on the Next.js documentation. It is only an illustration, not a complete setup. The file is a page in a Next.js project that uses the App Router, and it shows a list of the newest posts from WordPress, each linking to its own address.

// app/blog/page.js in a Next.js project (App Router)
export const revalidate = 3600; // refreshed at most once an hour

export default async function Page() {
  const res = await fetch(
    "https://primer.bg/wp-json/wp/v2/posts?_fields=id,slug,title"
  );
  const posts = await res.json();

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          {/* WordPress returns the title as HTML */}
          <a
            href={`/blog/${post.slug}`}
            dangerouslySetInnerHTML={{ __html: post.title.rendered }}
          />
        </li>
      ))}
    </ul>
  );
}

The _fields parameter tells WordPress to return only the ID, the slug (the short name in the address) and the title of each post instead of every field. The title comes as HTML, because WordPress formats the text and may replace quotes and apostrophes in it with HTML entities. That is why the example inserts it as HTML.

When the site is built, Next.js fetches the posts and prepares a finished HTML page. Visitors get that page without WordPress being involved. Once an hour has passed, the next visitor still gets the saved version, while Next.js prepares a new one in the background and swaps it in when it is ready. If WordPress does not answer at that moment, the Next.js documentation says the last successfully generated version keeps being served.

Turning this into a real site takes much more: a page for every post, the images, titles and meta descriptions for Google, the sitemap, an error page and draft previews. All of it has to be programmed, while in classic WordPress the theme and plugins provide it out of the box.

When changes show up on the site

This is the first thing editors ask when they move to headless. In the example above, a new post appears in the list up to an hour after it is published, because the page is refreshed at most once an hour.

Refreshing can also be tied to publishing. Next.js has a function called revalidatePath that marks the saved version of a page as stale, and a little code in WordPress can trigger it every time an editor publishes or saves a change. The next visitor then gets the new version. Decide how quickly changes must appear when you order the site, because it affects both the build and the load on WordPress.

Why a headless site is faster

In classic WordPress the page is put together when a visitor asks for it. A cache plugin keeps finished copies, which helps a lot, but pages that differ for every visitor, such as the cart in a store, stay out of the cache and go through PHP and the database every time.

In a headless site, pages are prepared in advance and served from a cache, without waiting for PHP and the database. They can also be delivered through a CDN, a network of servers that keep copies of pages and files closer to the visitors. According to web.dev, this means the request does not have to travel to the origin server, and the time to first byte can improve significantly.

Search engines benefit too. In its documentation on JavaScript sites, Google recommends rendering pages on the server or in advance, because pages then load faster for both people and crawlers, and some bots cannot run JavaScript at all. Next.js works exactly this way, so search engines get finished HTML.

The approach on its own does not guarantee speed. Heavy images, many fonts and third-party scripts slow a Next.js site down too, and ad pixels and chat widgets added later lower the score. So measure before and after every big change. Our guide on how to measure site speed with PageSpeed Insights explains how to read the result.

What changes for security

In classic WordPress the login form, the plugins and the theme sit at the same address as the site. Bots crawl the internet constantly, looking for wp-login.php, weak passwords and plugins with known vulnerabilities.

With headless, visitors only talk to the Next.js site. WordPress has to be reachable for it, but not for the whole internet, so the admin can be hidden, for example by allowing access only from certain addresses. Then the WordPress login form and plugins are not exposed to the bots.

This reduces the ways in, but it does not remove them. The Next.js site has its own dependencies, which need updates too. WordPress still needs updates and vulnerability checks even when it is hidden, because a vulnerable plugin is still vulnerable. We cover this in detail in the guide on headless WordPress and security.

More freedom in design

A WordPress theme decides a lot, from the structure of the pages to which styles and scripts load. Changes outside its limits often mean building on top of someone else's code, and every plugin adds its own files to the page.

With headless, the public site is built from scratch for you. The designer is not limited by a theme or a page builder, and the developer decides what loads on each page. That makes it easier for the site to look exactly the way you imagined and be fast at the same time.

For editors the work stays familiar. Pages are put together from ready blocks made for your design, which they arrange in WordPress without a developer. The blocks, though, are only the ones that were built. A new kind of section without a block has to be added in code.

What headless costs

The advantages come at a price that is worth knowing before you sign.

• Two systems instead of one. WordPress and the Next.js site are built, hosted and updated separately. When something stops working, the cause may be in one part, in the other, or in the connection between them.
• Plugins for the public site no longer apply. Everything a plugin adds to the pages visitors see, such as sliders, forms, a cookie banner or speed optimisation, has to be built again in Next.js. Some plugins hand over their data through an API. Yoast SEO, for example, returns the metadata and structured data for every page, but the Next.js site has to print them.
• Page builders do not work. Elementor, Divi and similar tools lay out pages through the theme, and in headless the theme is not involved. If you use Elementor now and the site is slow, first read why Elementor slows your site down.
• Draft previews take extra work. The Preview button in WordPress shows the page through the theme. In a headless site, previews go through Next.js Draft Mode, which bypasses the cache only for the editor, and WordPress has to be set up to open the right address.
• The build costs more. The public site, the connection to WordPress, the SEO data and the previews all have to be programmed, while classic WordPress has them ready-made. How much more depends on the site and shows in the quote.

When headless is worth it

Headless makes sense where sales or readers depend on speed under heavy load.

• A growing online store. Product and category pages are prepared in advance and load fast even during campaigns and sales, while products and orders stay in WooCommerce. When this makes sense for a store is covered in our guide on classic WooCommerce versus a headless store.
• A content site with many visitors. These are media sites, portals and large company sites where every visit to classic WordPress puts load on the server. With headless, most visits never reach WordPress.
• A site in several languages. Each language version is a separate set of pages prepared in advance, so one more language does not make the site slower. The hreflang links that tell Google which pages are language versions of the same page are written once in code and apply to the whole site.

In all three cases WordPress still needs a good server. The editors and the page refreshes go through it, and in a store every order does too.

When classic WordPress is the better choice

A small company site with a dozen pages that is edited twice a year gains almost nothing from headless. A well-built classic WordPress site with a light theme, good hosting and a cache is fast, and it costs less to build and maintain. One system is also simpler to keep updated.

Classic WordPress is also better when you rely on plugins that change the public site, or when you want to lay out pages yourself with a page builder. If the site hardly ever changes, consider even a static site, meaning a set of ready HTML files with no database. It is fast, and there is almost nothing on it to attack.

If you are unsure, start with classic WordPress. Content written in the WordPress editor stays in the database and can be shown by a headless site later. Content made with a page builder is harder to reuse, because it is tightly tied to the builder.

Checklist

• You know who will write the content and how often the site will change.
• You have measured the current site in PageSpeed Insights on mobile and know what slows it down.
• You have a list of the plugins that change the public site and know who will rebuild them in Next.js.
• If you use a page builder, you accept that it goes away.
• The quote includes draft previews, the SEO data, the sitemap and redirects for the old addresses.
• It is clear whether the admin will be hidden from the internet and how you will log in.
• You know who will update WordPress and the Next.js site after launch.
• You have compared the costs with those of a well-built classic WordPress site.

Do you have to decide this alone?

If your site is small and rarely changes, you do not need headless and there is no reason to think about it further. If you have a growing store or a busy site, the answer depends on your plugins, your traffic and your team. The page on website and online store development describes the three options we work with, from a classic WordPress site for a small business to a headless online store and headless WordPress for large sites. Tell us about your site and we will recommend the option that fits it, including the simpler one if that is enough.

Sources

• WordPress, REST API Handbook
• WordPress, REST API Reference, Posts
• WordPress, REST API Global Parameters
• WordPress, REST API Frequently Asked Questions
• WordPress, wptexturize()
• WordPress.org plugins, WPGraphQL
• Next.js, Documentation
• Next.js, Incremental Static Regeneration (ISR)
• Next.js, Caching and Revalidating
• Next.js, Draft Mode
• web.dev, Content delivery networks (CDNs)
• Google Search Central, JavaScript SEO basics
• Google Search Central, Localized versions of your pages
• Yoast, REST API