Building the Next.js 9.4 WordPress Example

A bit of history

Before I go into how I got involved with building the NextJS 9.4 WordPress Example, let me give you some background. In the spring of 2019, I was nose-deep in Gatsby. It was all I could think about. I loved how working with JavaScript and React made me feel, it was like I was transported back to 2007-2009, when I was first building themes for WordPress; the possibilities seemed endless.

I was having so much fun, I had become a regular contributor to the Gatsby project on Github, was invited by Jason Lengstorf to be a guest on his show, and converted my personal blog to Gatsby. To help prepare the engineering team for this new initiative, I presented a talk on Gatsby at our annual company retreat and invited Jason Bahl, the maintainer of WP GraphQL, to do a Lunch & Learn for our team. Our engineers got busy building a Gatsby + WordPress starter.

In the meantime, our Business Development team started pitching Gatsby during on-site meetings with clients who were interested in keeping their content workflows in WordPress, but wanted to move their frontend to the Jamstack. I felt like WebDevStudios (WDS) was positioned and ready to start rolling out headless WordPress sites with Gatsby.

But before you could say “headless,” major events happened at WDS, which required our full attention on other things; and the rest of 2019 was all about scaling up our team, restructuring leadership, and refining processes to accommodate the explosion of new clients and team members. We even archived the Gatsby + WordPress starter because we couldn’t devote any extra time to it. Needless to say, I didn’t write much JavaScript the second half of 2019 and all excitement I had about React and JavaScript went away as my role as a director had me busy with other things.

As part of the incredible growth and client projects that involved Gutenberg, I rolled out a company-wide React and Gutenberg training program in January 2020. The goal was simple: be the best damn Gutenberg shop out there. Engineers were paid to take online courses, build cool stuff, and then blog about it.

In February 2020, one of our major enterprise clients came to us with a huge ask: help them move about 70 WordPress sites to a Next.js frontend. “Holy $#!%,” I thought. Instantly, the JavaScript flame was reignited. All of our React and Gutenberg training is going to pay off.

Time to Learn Next.js

I had dabbled with Next.js before Gatsby, and one of our talented Frontend Engineers, Jo Murgel, wrote a really great series about creating a headless WordPress and Next.js project. The team also had some practice with PostLight’s Next.js/WordPress Starter , but honestly, WDS had no practical experience with this Next.js on a client project. It was time to put my head down and started learning, so I could be a bit more informed when working with this client’s requests.

The first thing I did was visit The course was a lot of fun, and I really loved the gamification aspect of it. In the coming days, I was building little things here and there using Next.js and WordPress. It was an exciting week and those old feelings from 2007-2009 were flooding back.

My Experience

I really, really love working with Next.js. It just “gets out of the way,” so you can focus on actually building something.

  • It’s not opinionated. Bring your favorite tools.
  • No need to know Node.js.
  • No need to import React or Fetch. They’re already there.
  • No need to learn GraphQL (unless you want to use it).
  • No need to mess around with Webpack, plugins, or config files.
  • No need to configure Routing.
  • It can build both static and server side rendered pages.
  • It can also fetch data and build a static page.
  • Builds are instant; no waiting around for all your images, GraphQL queries, and pages to process. You can have a static site that literally updates in seconds.
  • You can write CSS, CSS modules, or Sass without any plugins.

To me, Next.js is somewhere between Create React App and Gatsby. By being “out of your way,” Next.js lets an engineer focus on building React components or styling the frontend using Tailwind CSS. In my opinion, that’s a better use of my time, than say fighting with the very framework that is supposed to help me. Kind of like how using a bare-bones starter theme for WordPress, like wd_s, can often be faster than a theme with all the bells and whistles.

Over the next few weeks, I continued to build little things, demoing them to the engineering team, and eventually shipped a Reddit Image Viewer app. The whole developer experience is extremely satisfying, and honestly, a whole lot of fun!

What having fun looks like on Github 😉

I was starting to feel very confident in my abilities, which meant I could help lead our team and tackle this potentially huge project.


In March 2020, COVID-19 quite literally shut down a major enterprise client. They were forced to suspend projects… including ours. Disappointed, but not deterred, we continued to learn and build things; including attending React Bootcamps, and we even tried to re-create When the pandemic is over, I believe the client will still want to do their project, and WDS will be ready.

Building the Next.js WordPress Example

There are 200+ examples built and maintained by the Next.js core team. The examples are there to help guide your learning and decision making. That’s also a lot of things to maintain, so I started contributing to them. I figured the core team was helping me learn and the least I could do was contribute back on examples, like DatoCMS. One thing always bothered me about the examples though, there wasn’t one for WordPress. I thought about opening a PR and building a Next.js + WordPress example until I saw this discussion. The core team was already working on one!

A few days later, I saw this PR come in: and took action by leaving this comment.

👋🏻  I’m the Director of Engineering for a WordPress agency and we want to start using Next.js on projects. We’ve been working internally on a WordPress starter based on the WP REST-API, and are quickly realizing the challenges with REST.

Since we’re really interested in moving away from REST, we had Jason Bahl, give a presentation to our engineers about GraphQL. I’m excited to see this example, and am interested in helping out.

Before I jump in, I wanted to see if y’all were open to me (and possibly my team) testing and providing feedback on this PR.

Thanks for your time!

The Co-author of Next.js (and WP GraphQL contributor), Tim Neutkens, replied and gave me the green light.

> Before I jump in, I wanted to see if y’all were open to me (and possibly my team) testing and providing feedback on this PR.

For sure! let us know 🙏

> Since we’re really interested in moving away from REST, we had Jason Bahl, give a presentation to our engineers about GraphQL. I’m excited to see this example, and am interested in helping out.

Funny you’re bringing that up, I was one of the first contributors to wp-graphql 😄

Then, I reached out to, Luis Alvarez, a Core Developer at Vercel and asked for collaborator access to the PR. He granted me access; we got right to work.

Luis had already laid the groundwork, and the PR was ready to be hooked up to a WordPress site. So, I spun one up on WP Engine, followed the Readme, and in just a few minutes, had a local running. I identified a few things we could improve:

@lfades Thanks for the colab access. 🙌🏻

I stood up a WP Engine site: and configured it based on the README. Then spun up this PR on my local, and everything worked on the first try! 👍🏻

After setting up some posts and pages (like a WordPress dev would normally do) and clicking around on my local, here are some other items that we should discuss…

  • Content (Gutenberg) blocks display in this example out of the box, but, there are styling issues. Specifically, center/right text alignment, links aren’t underlined, full-width blocks aren’t full-width. I may add some basic CSS and I’ll try not to deviate from this blog template, I just want the dev experience to be less “abrupt”.
  • How do we link to and display pages?
  • What about adding a menu?
  • What about displaying/linking tags and categories?
  • In WordPress, post titles support emoji and HTML entities, which are showing weird on my local. We’ll need to escape those.
  • Displaying custom post meta is probably outside the scope of this example, but it’s heavily used in the WordPress space. I think we should at least mention how to work with it in the README.

Thanks again and looking forward to collaborating! 😄

After some back and forth, we had a plan, and I started commiting to the PR. The end result looks like:

screenshot of next.js wordpress example
Click for the full image

What to Expect

The initial Next.js WordPress Example isn’t a full-blown starter. Instead, the core team plans to release more examples that include deeper integration with things like Pages, Menus, and custom post meta. For now you can expect:

  • Blog posts with Gutenberg block styles (that look pretty great)
  • Blog posts that route to their slugs
  • Featured image support
  • Displaying categories and tags
  • GraphQL powered queries
  • Tailwind CSS support

The example should help engineers who are looking for a way to get started integrating Next.js and WordPress.

Wrap Up

WebDevStudios was excited to partner with Vercel to help create this example. The core team was very gracious and we appreciate their help and patience. We plan on writing a follow-up blog post, which will deep-dive into getting up and running with this new example. We also want to continue contributing to more WordPress examples, and provide our clients with headless solutions using Next.js and WordPress.

Look for the Next.js + WordPress example on Github.


Have a comment?

Your email address will not be published. Required fields are marked *

accessibilityadminaggregationanchorarrow-rightattach-iconbackupsblogbookmarksbuddypresscachingcalendarcaret-downcartunifiedcouponcrediblecredit-cardcustommigrationdesigndevecomfriendsgallerygoodgroupsgrowthhostingideasinternationalizationiphoneloyaltymailmaphealthmessagingArtboard 1migrationsmultiple-sourcesmultisitenewsnotificationsperformancephonepluginprofilesresearcharrowscalablescrapingsecuresecureseosharearrowarrowsourcestreamsupporttwitchunifiedupdatesvaultwebsitewordpress