{"id":31946,"date":"2025-08-04T17:33:27","date_gmt":"2025-08-04T22:33:27","guid":{"rendered":"https:\/\/wpengine.com\/builders\/?p=31946"},"modified":"2025-08-07T15:37:45","modified_gmt":"2025-08-07T20:37:45","slug":"next-js-wordpress-routing-and-graphql","status":"publish","type":"post","link":"https:\/\/wpengine.com\/builders\/next-js-wordpress-routing-and-graphql\/","title":{"rendered":"Next.js + WordPress: Routing and GraphQL"},"content":{"rendered":"\n

Next.js<\/a> is one of the most popular front-ends for building with headless WordPress<\/a>. My Reddit notifications are littered with Next.js + headless WordPress recommendations. Today, we\u2019re going to look at implementing routing and data fetching for headless WordPress with Next.js.<\/p>\n\n\n\n

You may wonder why we\u2019re covering this, since WP Engine is behind Faust.js<\/a>, which provides its own routing solution for headless WordPress + Next.js sites. Faust\u2019s routing solution isn\u2019t perfect, however. In this article, we\u2019ll experiment with another approach that offers improvements. We\u2019ll be working with the Pages Router<\/a>, though many of the concepts could be translated to the App Router<\/a>.<\/p>\n\n\n\n

The two major issues we\u2019ll be looking at today are bundle splitting and query optimization. Currently, the catch-all route doesn\u2019t bundle template code separately. While this might only cause a couple of KB of bloat on small sites, the more complexity you add means you might be loading 10-100 KBs of extra code on every route.\u00a0<\/p>\n\n\n\n

When Faust was first conceived years ago, I don’t think the team fully understood the importance of small queries. Because of this, Faust\u2019s main mechanism for querying GraphQL only allows for one query per template. We have since learned that this is an antipattern. Just because you can query everything you need from GraphQL in one request doesn\u2019t mean you should. In this post, we\u2019ll also experiment with alternative ways to handle data fetching.\u00a0<\/p>\n\n\n\n

For a working example of what we discuss here, check out the wpengine\/hwptoolkit<\/a> repo.<\/p>\n\n\n\n

\n

Note<\/strong>: We recently announced<\/a> that we\u2019re working on improving Faust. The work I did for this article and much more is going into improving Faust.<\/p>\n<\/blockquote>\n\n\n\n

Routing<\/h2>\n\n\n\n

In the article on Astro<\/a>, we discussed four major steps in the template hierarchy that must be recreated for a front-end framework. URI => Data => Template => Render: Data + Template.<\/p>\n\n\n\n

In our article on SvelteKit<\/a>, we experimented with new routing methods due to its implementation details. Next is similar in that middleware and rewrites just won\u2019t work for us.  However, unlike SvelteKit, Next doesn\u2019t have a way to load components outside of components. <\/p>\n\n\n\n

Ne<\/span>xt.js does have the ability to dynamically import components, which will solve our bundling issue. Our template loader will only dynamically import the needed template, not all templates.<\/p>\n\n\n\n

Template Hierarchy in Next.js<\/h2>\n\n\n\n

Let\u2019s put this all together in Next.js. The steps are:<\/p>\n\n\n\n

    \n
  1. Get the URI<\/li>\n\n\n\n
  2. Determine the template\n