WordPress is used on over 1.3 billion websites across the world, and it works great as a Headless CMS. NextJS is a framework built on React to give you an amazing amount of features, which you would otherwise need to set up yourself (static rendering, bundling, prefetching etc), and provides super fast and performant websites. Let's combine the two to create a super fast headless WordPress website!
Pre-requisites:
- A basic understanding of NodeJS and React
- An existing WordPress website with some posts and page
We'll be using Colby Fayock's Next.js WordPress Starter in this walkthrough (https://github.com/colbyfayock/next-wordpress-starter/). This Next.js WordPress Starter project aims to "take WordPress as a headless CMS and use Next.js to create a static experience that can be deployed anywhere."
The Next.js WordPress Starter project allows us to easily pull everything you would normally expect to be in a WordPress website (posts, pages, author listings, global search) and brings it into NextJS through a GraphQL endpoint. The project is actively under development, so watch the repo for further feature updates!
Getting started
WordPress
The Next.js WordPress Starter uses GraphQL, so start by logging into your WordPress website and install WPGraphQL. If you don't have an existing WordPress website, I've set up a dummy project you can use instead at: https://fake-data.better-wordpress.dev.
Next.js WordPress Starter
The quickest way to get started with NextJS for the frontend is by opening your terminal, navigating to the folder you want to start working in, and running:
yarn create next-app -e https://github.com/colbyfayock/next-wordpress-starter
Once that's finished installing, open up your code editor and add an .env.local file to the root of the project. This is where we're going to set up our Environmental Variables, so that NextJS knows where to get our data from.
The Environmental Variable the Starter Project uses is: WORDPRESS_GRAPHQL_ENDPOINT, so I'm using WORDPRESS_GRAPHQL_ENDPOINT="https://fake-data.better-wordpress.dev/graphql" to get some dummy data. You can use this dummy WordPress data too while testing, but don't forget to replace the url with your own WordPress endpoint when you're ready to go live!
Back in your terminal, running yarn dev starts up a development server. This isn't the time to be looking at performance and bundle size of your new NextJS website (a mistake I made when first experimenting with NextJS), although you should always be making sure you ship as small a bundle size as possible. We'll get to that later on.
After running yarn dev in your terminal, you can now open up your browser and see your Headless WordPress site running at: http://localhost:3000.
Congratulations -- you now have a fully headless WordPress website running on the JAM stack, which includes all of you posts, pages and a live search! If you're using my fake data API, then your site should look similar to this screenshot:
Screenshot of data coming from a Headless WordPress installation running on NextJS
At this point, you can start to customise the starter project to look and function exactly how you want it to. And when you're done, it's time to deploy your website for the world to see!
Deploying your NextJS website
Before you run a production build, update your package.json file with your live URL (on line 3). This is the URL which will be passed into your sitemap -- very important for SEO.
Running yarn build in your terminal will actually fetch all of your posts and pages, create a sitemap and an optimised production build of your static website ready to deploy to your server.
After running yarn build, you can then run yarn start to run a local server and test your local production build. This is the perfect time to be looking at your bundle sizes and site speed, as it's a good representation of how your site will respond on a server.
I use vercel.com to deploy better-wordpress.dev. Vercel are the same team who built NextJS, and they have a generous free tier, so it makes perfect sense to deploy it there.
I'm currently working on blog posts explaining how to deploy NextJS to Vercel, Netlify and other hosts -- but in meantime the Vercel docs are pretty great: https://nextjs.org/docs/deployment
Final words
You now have a fully featured and blazingly fast website running on the JAM stack, using NextJS on the frontend and WordPress for your data.
Top comments (2)
Hi! Nice tutorial you have there.
One concern: Does the wordpress website need to be online before using this method?
I'd love to use my local development version as a headless cms
Hi Stephane. Yes - you'll still need to host your WP instance online. Netlify/Vercel will need to connect to the site when it performs the build (they won't be able to connect to your localhost).
The other option, if you don't want to have a WP instance online, is to do the build on your local machine and push the static build up to Netlify via Git (docs.netlify.com/site-deploys/crea...). Then there will be no build step on Netlify, so no need to connect to a WP site online.