I\u2019ve been using headless WordPress since before it was cool. I\u2019ve built numerous sites using Gatsby, Next.js, SvelteKit, and now Astro! <\/p>\n\n\n\n
I can wholeheartedly say Astro has been the best experience for me. While it should stand proud for various reasons, its feature set and approach make it an excellent match for use with headless WordPress.<\/p>\n\n\n\n
In preparation for this article, I moved a site from Gatsby to Astro. I learned a ton about Astro and hope to share that with you over a series of articles. Today, I\u2019ll share how I handled routing and querying WPGraphQL. <\/p>\n\n\n\n
If you\u2019re unfamiliar with Astro, scan their home page<\/a> and reference their docs as needed. A working example of what I\u2019m building is also available in the wpengine\/hwptoolkit<\/a> repo!<\/p>\n\n\n\n Table of Contents<\/strong><\/p>\n\n\n\n Routing between WordPress and a headless app can be surprisingly complex. WordPress is unique in this aspect due to its opinionated nature. Myself and others on my team have recently written extensively on the complexities of routing<\/a> if you want to read more. <\/p>\n\n\n\n You need to know now that teaching your frontend to route and template like the WordPress Template Hierarchy<\/a> has some significant advantages. We implemented this in Faust,<\/a> but it has some drawbacks due to how Next.js works. <\/p>\n\n\n\n Astro\u2019s flexibility and server-first model made implementing WordPress-style routing and templating a breeze with no drawbacks.<\/p>\n\n\n\n The template hierarchy in WordPress can be complex and confusing. <\/p>\n\n\n\n If you’re from the WordPress world and understand how its routing works\u2014great! You’ll still benefit from this section by learning how routing typically works in most JavaScript frameworks. For everyone else who may not be as familiar with WordPress routing, don’t worry\u2014let\u2019s break it down and make sense of it together.<\/p>\n\n\n\n Most JavaScript-based meta-frameworks route using \u201cFile System\u201d routing. The specifics vary, but the idea is that the names of the files and folders determine what is rendered at a given route. Astro is no exception<\/a>. File system routers make some assumptions, though. <\/p>\n\n\n\n A given route is tied to a specific piece or type of data (e.g., blog posts) and template (e.g., all data at that route should be rendered roughly in a single way). For the route WordPress flips this flow because it thinks about data first. A given post or page can be at any route and rendered with a variety of templates. The WP Permalinks<\/a> system determines the full route (URI) of the content and the Template Hierarchy determines, based on the data, configuration, and available templates (templates are provided by a theme in WordPress). Only then is a page rendered. This system is extremely flexible and powerful. <\/p>\n\n\n\n Practically, this flow does look a little different. When a request for This is the flow we\u2019ll have to mimic in Astro. URI => Data => Template => Render: Data + Template.<\/p>\n\n\n\n In Astro, this will look like 6 distinct steps:<\/p>\n\n\n\n <\/p>\n\n\n\n Does your brain hurt? Sorry, all will be explained. <\/p>\n\n\n\n We need the URI, the whole thing, not just a sub-path. This is easy in Astro with a catch-all route We\u2019ll then need to fetch the data associated with that URL. The good news is that WPGraphQL has the perfect tool for the job! <\/p>\n\n\n\n This is an extremely simplified version of the Seed Query. The full Seed Query<\/a> I\u2019m using in the example implementation has to handle all content in WordPress with a URI (posts, pages, custom posts, taxonomies, authors, etc), even if it\u2019s unpublished draft content. This is the same seed query used by Faust. <\/p>\n\n\n\n All that aside, now that the data has been retrieved from WordPress, we can determine what template to render. This is where things get complicated.<\/p>\n\n\n\n We have a data set from our seed query. But what template will render this data? <\/p>\n\n\n\n In the case of the seed query, we could simply ask WordPress. But there is no easy WordPress functionality to get this data. My example uses the function we built for Faust<\/a> to take the data from the seed query and generate a list of possible templates. This list is in order of most specific to least specific. For a page, this looks like: To render this WordPress data, we need a template, and unless we want them all to look identical, we have to break out of the file system router. Our one catch-all route needs to be able to render multiple templates.<\/p>\n\n\n\n The logical assumption here might be to use a switch statement or key\/value pairs to select from a variety of registered templates. This is how Faust works. <\/p>\n\n\n\n While this will work technically, there are issues with bundling. File system routes bundle code on a per-route basis. In Next.js this means the JS for all routes are in a single bundle due to the use of a catch-all route. <\/p>\n\n\n\n Astro has similar bundling issues<\/a> (technically, if you don\u2019t ship any JS, this isn\u2019t an issue, but that\u2019s an unlikely scenario in reality). Because of this, standard JavaScript won\u2019t work. We need to work with the file system router to get bundling to work correctly.<\/p>\n\n\n\n The solution is to use \u201crewrites\u201d. Rewrites are a web server term. If you\u2019re running a web server like Apache and use a basic setup to serve PHP or HTML you\u2019ll notice all your routes look like These aren\u2019t \u201cpretty\u201d. Rewrites let me configure Apache to serve These are distinct from more common \u201credirects\u201d because we don\u2019t tell the browser to look somewhere else. Rewriting renders something other than what was requested without changing the URL. <\/p>\n\n\n\n Rewrites let our catch-all route determine what template to use and rewrite the user’s request to the template route. So my routes in Astro<\/a> now look like this: <\/p>\n\n\n <\/p>\n\n\n\n I now have 4 available templates. One issue here is someone could accidentally route directly to Finally, we don\u2019t want to hard code available templates into our JS code because it\u2019s cumbersome and error-prone. I chose to use Astro\u2019s Content Collections<\/a> feature to easily read available templates<\/a> directly from the file system.<\/p>\n\n\n\n We now have a list of possible templates and a list of available templates. Based on the prioritized list of possible templates, we can determine which of the available templates to use. <\/p>\n\n\n\n A quick bit of JavaScript<\/a> can compare the list of possible templates ( Now that we\u2019ve built all the pieces, we can put this into a single function<\/a> that takes a URI and returns the template. Our catch-all route<\/a> now looks something like this:<\/p>\n\n\n <\/p>\n\n\n\n The specifics look slightly different depending on whether you\u2019re server rendering at build time or on request. The full example shows rendering statically at build time.<\/p>\n\n\n\n Routes are routing and our frontend is happily relying on the WordPress template hierarchy to route. Now, we want to render data, but our seed query didn\u2019t have much in it! We could expand that query, but this isn\u2019t recommended. <\/p>\n\n\n\n While it is possible to get a lot of data from a single GraphQL request, this lowers caching hit rates. We\u2019d rather make several specific queries to GraphQL that are highly cachable than one large query that has a low cache hit rate due to being constantly invalidated. So, we\u2019re going to want to query data for each template. <\/p>\n\n\n\n There are plenty of great GraphQL clients out there, like Apollo. I chose URQL<\/a> for this demo to learn something new and for its minimalist approach. URQL is an excellent choice with plenty of advanced features that can be added if your project demands. It paired great with Astro!<\/p>\n\n\n\n\n
\n
\n
\n
Routing<\/h2>\n\n\n\n
Basics of the Template Hierarchy<\/h3>\n\n\n\n
\/blog\/[slug].astro<\/code>, the [slug].astro<\/code> template renders a blog post as fetched by slug<\/code> the same way it renders every other blog post. File system routing is robust and suited to solve the unique problems of JS web apps.<\/p>\n\n\n\n\/blog\/a-blog-post<\/code> comes into a WordPress site, the server only has that URI\u2014it doesn\u2019t magically know the data. WordPress uses the permalink system to look up the associated piece of data before choosing a template and rendering the page. <\/p>\n\n\n\nTemplate Hierarchy in Astro<\/h3>\n\n\n\n
\n
Catch-All Route<\/h4>\n\n\n\n
pages\/[...uri].astro<\/code>. <\/p>\n\n\n\nSeed Query<\/h4>\n\n\n\n
<\/p>\n\n\nquery SeedQuery($uri: String!) {\n<\/span><\/span> nodeByUri($uri) {\n<\/span><\/span>\u00a0 __typename\n<\/span><\/span>\u00a0 id\n<\/span><\/span>\u00a0 ... on ContenNode {\n<\/span><\/span>\u00a0\u00a0\u00a0\u00a0 slug\n<\/span><\/span>\u00a0 }\n<\/span><\/span> }\n<\/span><\/span>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nCalculating the Possible Templates<\/h4>\n\n\n\n
[page-sample-page, page-2, page, singular, index]<\/code>.<\/p>\n\n\n\nCreating Available Templates<\/h4>\n\n\n\n
\/about.html<\/code> or \/blog-post.php?slug=headless-wordpress-rocks<\/code>. <\/p>\n\n\n\n\/about.html<\/code> when a request comes in for \/about<\/code>. Or a request for \/blog\/headless-wordpress-rocks<\/code> to ask the PHP for \/blog-post.php?slug=headless-wordpress-rocks<\/code> and to serve that. <\/p>\n\n\n\npages\/\n<\/span><\/span>\u00a0\u00a0\u21b3\u00a0 [...uri].astro\n<\/span><\/span>\u00a0\u00a0\u21b3\u00a0 wp-templates\/\n<\/span><\/span> \u21b3\u00a0 index.astro\n<\/span><\/span> \u21b3\u00a0 home.astro\n<\/span><\/span> \u21b3\u00a0 archive.astro\n<\/span><\/span> \u21b3\u00a0 single.astro\n<\/span><\/span><\/code><\/span><\/pre>\n\n\n\/wp-templates\/home<\/code> or any of these routes. To solve for this I have a check<\/a> at the top of all templates to make sure this isn\u2019t the case, if it is, I rewrite to a 404 page.<\/p>\n\n\n\nChoosing a template<\/h4>\n\n\n\n
[single-post-sample-post, single-post, single, singular, index]<\/code>) to the list of available templates ([archive, home, archive, single]<\/code>) and the first match is our template. In this case \u201csingle\u201d is the winner!<\/p>\n\n\n\nPutting it all together<\/h4>\n\n\n\n
---\n<\/span><\/span>\/\/ ...<\/span>\n<\/span><\/span>\n<\/span><\/span>const<\/span> { uri = \"\/\"<\/span> } = Astro.params as<\/span> Params;\n<\/span><\/span>\n<\/span><\/span>const<\/span> results = await<\/span> uriToTemplate({ uri });\n<\/span><\/span>\n<\/span><\/span>if<\/span> (results.template) {\n<\/span><\/span>\u00a0\u00a0return<\/span> Astro.rewrite(results.template.path);\n<\/span><\/span>}\n<\/span><\/span>\n<\/span><\/span>---\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nQuerying Data <\/h2>\n\n\n\n
GraphQL Client<\/h3>\n\n\n\n