Awesome Open Source
Awesome Open Source

Next.js Headless WordPress

Project Status: Active. Stars Forks Contributors Follow

  • Headless WordPress, using Decoupled Architecture in Next.js
  • Backend in WordPress using WPGraphQL
  • Front end in React.


  1. Home Page, Blog Page, Post Page
  2. Post Preview
  3. Post Pagination.
  4. Load More Posts.
  5. SEO Component fetching data Yoast SEO with schema
  6. Cypress for tests, Eslint for linting.
  7. Apollo Client with GraphQL
  8. Api endpoints.
  9. Header and Footer in Next.js fetching from WordPress Menu items.
  10. WordPress Widgets displayed on Next.js frontend.
  11. Site title, tagline, copyright text, sourced from WordPress.
  12. Next.js Image component, that has image optimization at request time.
  13. Authentication with JWT and Http Only Cookie implementation.
  14. Login feature for WP Post Preview in Next.js
  15. Incremental Static (Re)generation and automatic creation of New Static post pages without having to re-build next.js the application.
  16. Gutenberg styles support

Tutorial Course

Code for the tutorial is in the Tutorial Branch

Live Demo Link


First clone/fork the repo and cd into it.

git clone
cd nextjs-headless-wordpress

It's very simple to setup the project with just one command and this ./nxtwp configure

One command project setup

The below command is going to set up the project in the interactive mode. It creates an .env file for front-end next.js project and setsup up frontend and/or backend. Run this from the root of the project.

./nxtwp configure

It's going to ask you a few of questions.

Q1. Do you already have a WordPress setup that you want to continue with? [y/n]:


y: If you would like to use this project's WordPress Docker setup ( In which case make sure to install and active all plugins from [backend/plugins-collection]) n: If you want to use your own WordPress setup.

Q2.   What is your WP backend URL? (defaults to http://localhost:8020): 

Leave it blank if you would like to use this project's WordPress Docker setup, else enter your own WordPress site URL.

  What is your frontend next js URL? (defaults to http://localhost:3000):

Leave this blank for development, as it will be the same as default for next.js

  What is your Disqus comments shortname? (leave blank if you are not using): 

Leave this blank if you are not going to use the Disqus comments, else enter your Disqus comments shortname.

This is going to automatically:

  • Creates the .env file in the frontend directory.
  • Setup WordPress backend with all the plugins via composer (if you chose y for the first question)
  • Install npm packages for next.js frontend and start development server.

WordPress Backend will be available on http://localhost:8020 Next.js Backend will be available on port http://localhost:3000

  • Make sure to activate all plugins that it has installed via composer.
  • Update block registry by going to WordPress Dashboard > GraphQL Gutenberg.
  • Update the permalink by going to Settings > Permalinks > Post name > Save
  • Copy the backend/wordpress/.htaccess file content into your WordPress .htaccess
  • For more information checkout the project Wiki

That's it!

During development

Useful commands: To be run from the root of the project.

./nxtwp configure       # Sets up backend and frontend and creates an .env file
./nxtwp start-all       # Creates and starts docker environment for WP and runs Next JS server
./nxtwp start-backend   # Creates and starts docker environment
./nxtwp start-frontend  # Installs all packages and Runs Next JS server
./nxtwp stop            # Stops the WordPress docker containers


  1. If you get 404 on frontend for graphql request, check to see that the .htaccess file in wordpress directory has the rules
# BEGIN WordPress
# The directives (lines) between "BEGIN WordPress" and "END WordPress" are
# dynamically generated, and should only be modified via WordPress filters.
# Any changes to the directives between these markers will be overwritten.
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

# END WordPress
  1. If front-end is throwing some other error.
  • Check if all the required WordPress plugins form backend/plugins-collection are active.
  • Ensure you have updated the block registry from WordPress backend > GraphQL Gutenberg
  • Ensure that .env file has correct env variables and their values in frontend/.env

References for Docker Images.

  1. phpMyAdmin

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,048,748
Reactjs (160,989
Plugin (113,985
Docker (97,011
Wordpress (29,592
Authentication (26,851
Graphql (15,617
Nextjs (10,491
Jwt (9,742
Seo (3,370
Headless Browsers (3,274
Cypress (2,103
Hacktoberfest2020 (1,930
Apollo Client (1,007
E2e Tests (742
Headless Cms (510
Nextjs Starter (130
Headless Wordpress (34
Yoast Seo (12