next-wordpress-starter turns a WordPress install into a static Next.js site

WordPress stays, only the front end changes

The premise of next-wordpress-starter is stated in one line: take WordPress as a headless CMS and use Next.js to create a static experience without any third party services that can be deployed anywhere. That last clause is the point of the project, because the usual way to put a React front end on WordPress is to add a hosted backend, a content API service or a database in the middle.

Here the chain is short. WordPress stores the content. WPGraphQL exposes it over GraphQL. Next.js queries that endpoint and renders the pages. The starter does not move your posts into a different system, it changes what reads them.

The feature list describes the scope as the set of things a WordPress theme is expected to provide out of the box, and the demo site is the evidence. It covers a blog, pages, individual posts, category archives, author archives, search through both client side global navigation and a search page, an RSS feed at /feed.xml and a sitemap at /sitemap.xml. The search is described as client side, which is a consequence of the static approach and worth understanding before you commit to it, because client side search needs the content in the browser.

The SEO work is also listed as a theme feature rather than a plugin concern: unique page titles, unique descriptions and Open Graph tags. The optional Yoast SEO plugin support is there for teams whose WordPress already runs it.

Three environment variables and one GraphQL endpoint

The configuration surface is small enough to read in one sitting, and the README gives a table for it.

| Name | Required | Default | Description | | ---------------------------------- | -------- | - | ------------------------------------------------- | | WORDPRESS_GRAPHQL_ENDPOINT | Yes | - | WordPress WPGraphQL endpoint (ex: host.com/graphl)| | WORDPRESS_MENU_LOCATION_NAVIGATION | No | PRIMARY | Configures header navigation Menu Location | | WORDPRESS_PLUGIN_SEO | No | false | Enables SEO plugin support (true, false) |

The endpoint is the only required value, and the file you put it in is .env.local at the project root.

WORDPRESS_GRAPHQL_ENDPOINT="http://wordpressite.com/graphql"

The README anticipates that the default form does not always work and gives the fallback, which appends index.php?graphql to the host. That is the shape of a WordPress install with pretty permalinks disabled, and the fact that the starter documents it tells you the project has been run against a range of real installs rather than only a tidy one.

The menu location variable is a small but real detail. It defaults to PRIMARY, and the README warns that some themes do not have a PRIMARY menu location, so a mismatch produces a header with no navigation rather than an error. The third variable turns on Yoast SEO support and defaults to false.

The environment section also notes that environment variables can optionally be statically configured in next.config.js, which is the escape hatch for a build environment where .env.local is not available.

The dependency list shows how the query is executed. @apollo/client at ^3.7.14 and graphql at ^16.6.0 handle the GraphQL requests, fuse.js at ^6.6.2 is a fuzzy search library, and the rest are rendering and styling pieces, with sass for stylesheets, react-helmet for the document head, rss for the feed, parameterize for turning post titles into slugs, he for HTML entity decoding, date-fns for dates, nextjs-progressbar for the route loading indicator and react-icons for the icon set.

Static export is a first class deployment target

The package.json gives the project two build paths, and the difference between them matters for hosting.

"build": "next build",
"export": "next export",
"start": "next start -p ${PORT:=3000}",

The start script uses a shell parameter expansion with a default of 3000, so the port follows the PORT environment variable that most PaaS providers set. The export script is the static one.

The README documents two ways to deploy to Netlify. The first is the Essential Next.js Plugin, described as recommended and offered as an option when you first import a project based on the starter. That route runs Next.js natively on Netlify and lets you use the framework features Netlify supports. The second is exporting the project, which lets Next.js compile the project into static assets including HTML files, allowing you to deploy the project as a static site directly to Netlify just like any other site. The README is specific about the mechanism: add next export to the end of the build command inside package.json, for example next build && next export.

For Vercel the path is simpler, since Next.js is a Vercel-supported project, so you import the project as a new site and configure your environment variables either during import or in the settings.

Both Netlify buttons and the Vercel clone button are in the README, and a netlify.toml file is in the repository root, which is where the Netlify specific build settings live. A.nvmrc file pins the Node version for the build, and the pnpm-lock.yaml shows pnpm as the lockfile, with the package scripts calling pnpm for linting and formatting even though the quick start offers both yarn and npm.

The static export path is the interesting engineering choice. It removes the Node server from production, so nothing has to run at request time, but it also means every page must be renderable at build time, which is what makes the client side search and the pre-generated feed and sitemap the natural shape of the design.

The plugins directory carries WPGraphQL with it

There is a plugins/ directory at the root of the repository, and its existence is a useful clue about the intended setup path. The directory suggests a place to keep the WordPress side plugin alongside the Next.js code, so a fresh WordPress install can be set up to serve GraphQL.

That matters because the GraphQL endpoint is not a generic REST URL. The schema exposed by WPGraphQL, the field names for posts, categories, authors, menus and the Yoast SEO data, is what the Next.js side queries. If the plugin is missing, misconfigured or a different version, the queries fail, and the failure will look like a rendering problem rather than a configuration one. Shipping the plugin removes one variable from that chain.

The src/ directory holds the application code, and jsconfig.json at the root provides the path aliases configuration. The.eslintrc.js,.prettierrc.js and.eslintignore files handle linting and formatting, with eslint-config-next, eslint-config-prettier, eslint-plugin-prettier and eslint-plugin-react composing the lint stack, and husky with a prepare script wiring the git hooks, backed by lint-staged which formats JavaScript with the lint fixer and SCSS with Prettier on commit.

Playwright is in the dev dependencies at ^1.33.0, so there is browser test tooling in the project even though the README does not document a test suite in detail. Whether those tests are runnable against a fresh WordPress install is not stated, which is a gap for anyone planning to rely on them in CI.

Where the headless approach stops being free

The first limitation is that WordPress is still there. The starter does not remove the database, the plugin updates, the security patching of a PHP application, or the host that runs it. It replaces the theme, so the work of running WordPress remains, and if the motivation was to shed that burden, this project does not do that.

The second limitation is search. The README lists search as client side global navigation plus a search page. Static output plus a full corpus of posts in the browser is workable for a blog of a few hundred posts and gets heavy for a large archive, and a site that needs server side search, or search across custom post types that are not in the GraphQL query, will need work that the starter does not provide.

The third limitation is the static export constraint on Next.js features. The README recommends the Netlify plugin precisely so the project can take full advantage of all native Next.js features Netlify supports with that plugin, which implies that the export path gives some of them up. A site that needs image optimisation at runtime, or server actions, or incremental regeneration, has to run on the plugin route or on Vercel rather than on pure static files.

The fourth limitation is editorial workflow. Two people editing in the WordPress admin at the same time is fine, but the publication trigger is the build. The static output reflects the content at build time, so a build hook has to be wired to the publishing flow, and the README does not describe one, which means it is a decision you have to make rather than a piece the starter hands you.

How it differs from a WordPress theme

The comparison worth making is with the thing this project is trying to replace, and the difference in approach is easy to state.

A traditional WordPress theme is a set of PHP templates that WordPress renders on every request. The server produces HTML, the theme controls the markup, and a visitor hitting the page triggers a PHP render. The starter inverts that: the server produces data over GraphQL at build time, Next.js produces the HTML, and the result is a set of files.

That inversion has concrete consequences. Performance improves because the response is a static file rather than a rendered page, and the deployment stops depending on a PHP runtime at request time. The cost is that anything dynamic has to be either moved to build time or to the client, which is exactly why the search is client side and why the feed and the sitemap are generated files. Layout flexibility improves too, because React components and a component library replace PHP template functions, and the Sass setup with a stylesheet build is the same workflow a front end developer already knows.

The comparison in the other direction is with a full static site generator, which keeps the content as files in the repository, so the editorial experience is a text editor and a pull request. This starter keeps a graphical editor, a media library, a revision history and a comment-ready admin, which is worth a great deal to an editorial team and would be a regression to lose.

The trade is therefore between editorial comfort and system simplicity, and the author of the repository is explicit that this is one path rather than the only one. The README points at a second, more basic starter for teams that want an MVP setup with WPGraphQL in WordPress, which is the sensible first step if you are evaluating the approach.

Editorial conclusion

next-wordpress-starter fits an editorial team that already runs WordPress and wants a fast front end without giving up the WordPress admin, and it fits a hosting setup that wants static output rather than a Node server, since next export is a supported deployment path. It does not fit a team that wants to move off WordPress entirely, because WordPress remains the content store, and it does not fit a site with a lot of interactive functionality, because the static export path and the GraphQL layer are built for content pages. Before adopting it, confirm your WordPress install has WPGraphQL active and that you know its endpoint, set WORDPRESS_GRAPHQL_ENDPOINT in .env.local, and note that the plugin directory holds the WPGraphQL plugin and that the project is MIT licensed with no GitHub releases, the last push having been on 2026-10-15.

Frequently asked questions

Official sources

1. colbyfayock/next-wordpress-starter on GitHub
2. Issues
3. License: MIT
4. Project website
5. README