{"cache":{"posts1":{"__typename":"RootQueryToPostConnection","nodes":[{"__typename":"Post","id":"cG9zdDo3OTY=","uri":"/blog/catching-the-cache-using-the-apollo-client-and-next-js-on-atlas/","seo":{"__typename":"PostTypeSEO","readingTime":6},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo3","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/c24a68b84c9ad2b53c633d14917d8298?s=96&d=mm&r=g"},"name":"Francis Agulto","description":"---\r\ntitle: Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"title0":"Catching The Cache using the Apollo Client and Next.js on Atlas","slug":"catching-the-cache-using-the-apollo-client-and-next-js-on-atlas"},{"__typename":"Post","id":"cG9zdDo3ODI=","uri":"/blog/atlas-search-facets-and-stemming/","seo":{"__typename":"PostTypeSEO","readingTime":5},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMQ==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/8ee8d4ed6d4b3a916be500eb1bcf03f4?s=96&d=mm&r=g"},"name":"Grace Erixon","description":"---\r\ntitle: Associate Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"title0":"Atlas Search: Facets and Stemming","slug":"atlas-search-facets-and-stemming"},{"__typename":"Post","id":"cG9zdDo0ODE=","uri":"/blog/what-is-faust-js-the-headless-wordpress-framework/","seo":{"__typename":"PostTypeSEO","readingTime":9},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMg==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/a64abda82041a00e479ecc2b156d7947?s=96&d=mm&r=g"},"name":"Jeff Everhart","description":"---\r\ntitle: Sr. Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"title0":"What is Faust.js?: The Headless WordPress Framework","slug":"what-is-faust-js-the-headless-wordpress-framework"},{"__typename":"Post","id":"cG9zdDo2Nzg=","seo":{"__typename":"PostTypeSEO","readingTime":21,"opengraphDescription":"In this tutorial, you'll learn how to build a headless WordPress site with the Astro framework using WPGraphQL"},"uri":"/blog/building-a-headless-wordpress-site-with-astro/","title0":"Building a Headless WordPress Site with Astro","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMg==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/a64abda82041a00e479ecc2b156d7947?s=96&d=mm&r=g"},"name":"Jeff Everhart","description":"---\r\ntitle: Sr. Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"date":"2022-11-18T20:00:06","content0":"\n

The WP Engine developer relations team is always exploring new technologies to see how they can make your job as a developer easier or more enjoyable. Sometimes, that means choosing the tools you already know and use, but other times it means trying something new because of the benefits it can bring you.

\n\n\n\n

In the vein of trying something new, I’ve been exploring the Astro framework over the last few weeks, and quite frankly there is a lot here to like for people interested in doing headless WordPress. By the end of this post, you should be able to do the following things:

\n\n\n\n

explain the key performance benefits and philosophy behind the Astro framework
create a basic headless WordPress site using Astro components and WP GraphQL

\n\n\n\n

To kick things off, let’s start by exploring what Astro does differently than some of the other frameworks we’ve looked at in the past. You can find the starter project that this tutorial references on GitHub.

\n\n\n\n

What is Astro?

\n\n\n\n

Astro bills itself as “an all-in-one web framework for building fast, content-focused websites.” Their emphasis, not ours. But there are two important terms in that statement that I want to discuss: fast and content-focused.

\n\n\n\n

Astro indeed builds some fast sites, but it does so by narrowing the audience it’s trying to serve as a framework to be mostly content-focused sites. In their documentation, they draw the distinction between a content-rich site and a web application, which might require auth, support data mutations, and need to manage application state. All of those scenarios require lots of JavaScript to implement, but most content-focused sites don’t have the same requirements. Frameworks like Next.js, Nuxt.js, and SvelteKit all handle the web app requirements well, but all of this requires additional energy and lines of code to support.

\n\n\n\n

By prioritizing this content-focused use case, Astro is able to double down on several key principles that might be foreign to anyone who’s worked in a recent JavaScript framework: zero JS by default, server-first paradigm, and component islands.

\n\n\n\n

When looked at in this context, there is a lot of overlap in the audience Astro is trying to serve and the people who make headless WordPress sites. Let’s explore what this pairing looks like.

\n\n\n\n

Getting Started with the WordPress CMS

\n\n\n\n

While there are a ton of ways to work with WordPress locally, with tools like MAMP, XAMPP, Vagrant, and even Docker, the quickest way to spin up a local WordPress site is using the Local development environment.

\n\n\n\n

After downloading the software, we can create a local WordPress site for this project in a few clicks:

\n\n\n\n

\n\n\n\n

If you have a pre-existing WordPress site, you can use that as well.

\n\n\n\n

After you’ve got a basic WordPress site either locally or on a server somewhere, we can install the WPGraphQL plugin from the plugin repository and activate it.

\n\n\n\n

\n\n\n\n

After we install and activate the plugin, we gain access to a GraphQL menu option that provides us with an interactive IDE we can use to construct and test our GraphQL queries.

\n\n\n\n

\n\n\n\n

By default WPGraphQL makes a GraphQL endpoint available at the /graphql path of you site domain.

\n\n\n\n

Getting Started with Astro

\n\n\n\n

To help you get started using Astro and WordPress faster, we created a starter project with some good defaults that we’ll walk through in the steps below.

\n\n\n\n

First, you’ll need to clone the repository to your machine. Run the following commands to clone the starter repo, change directories, and install dependencies:

\n\n\n\n

$ git clone https://github.com/JEverhart383/astro-wordpress-starter.git\n$ cd astro-wordpress-starter\n$ npm install

\n\n\n\n

Now that we have our project ready to go, let’s create an .env file in your root directory and add the following property:

\n\n\n\n

WORDPRESS_API_URL = https://<your-wordpress-site>/graphql

\n\n\n\n

After saving the .env file, run the following command in your terminal to start the project in development mode:

\n\n\n\n

$ npm run dev

\n\n\n\n

With the project running, you should be able to visit localhost:3000 and see a homepage that looks like this with your ten most recent posts:

\n\n\n\n

\n\n\n\n

From this starting point, we can look at a few of the different features of Astro as we examine a few different pages and how they are constructed.

\n\n\n\n

Astro and File-based Routing

\n\n\n\n

Like many other current meta-frameworks, Astro implements a file-based routing strategy using a pages directory that can contain Astro components, markdown, MDX, or even HTML. The structure of our pages directory looks like this:

\n\n\n\n

/pages\n     [...uri].astro\n     index.astro

\n\n\n\n

Let’s start by looking at our index.astro component to see how it is structured before we dig into our more complex dynamic route. Like other frameworks that enable file or page-based routing, the index.astro component is what gets rendered at the root of our site:

\n\n\n\n

---\nimport Hero from \"../components/Hero.astro\";\nimport PostCard from \"../components/PostCard.astro\";\nimport MainLayout from \"../layouts/MainLayout.astro\";\nimport { homePagePostsQuery } from \"../lib/api\";\n\nconst data = await homePagePostsQuery();\nconst posts = data.posts.nodes;\n\n---\n\n<MainLayout title='Home Page'>\n\t<main>\n\t\t<Hero></Hero>\n\t\t<h2>Recent Posts</h2>\n\t\t{\n\t\t\tposts.map(post => {\n\t\t\t\treturn (\n\t\t\t\t<PostCard post={post}></PostCard>\n\t\t\t\t)\n\t\t\t})\n\t\t}\n\t</main>\n</MainLayout>

\n\n\n\n

Astro components have two main parts to them: the component script, which is contained within the code fence (---), and the template which can contain other Astro components, HTML, or even other framework components. Astro components are super flexible: they can take props and implement slots, load other components, scope styles at the component level, and offer JSX-like expressions to manipulate markup programmatically.

\n\n\n\n

It’s important to remember that Astro has no client-side run time though, so any code inside of the component script is executed on the server and the components all render HTML at build time.

\n\n\n\n

Building a Homepage

\n\n\n\n

Let’s take a look at what our index.astro component is doing in more detail. At the top of the file, we define the component script and import a few other Astro components, as well as load some data from our WordPress backend:

\n\n\n\n

---\nimport Hero from \"../components/Hero.astro\";\nimport PostCard from \"../components/PostCard.astro\";\nimport MainLayout from \"../layouts/MainLayout.astro\";\nimport { homePagePostsQuery } from \"../lib/api\";\n\nconst data = await homePagePostsQuery();\nconst posts = data.posts.nodes;\n\n---

\n\n\n\n

When we declare variables in our component script, they are available inside of our template. So, when we initilize the posts variable from the result of our GraphQL query, we can use that in our template to create dynamic markup using JSX-like syntax. In the example below, we call posts.map and return a PostCard component that accepts the post data as a prop:

\n\n\n\n

{\n\tposts.map(post => {\n\t\treturn (\n\t\t<PostCard post={post}></PostCard>\n\t\t)\n\t})\n}

\n\n\n\n

The PostCard component does most of the heavy lifting in displaying the details of the post on in the list on the homepage, so let’s see what that looks like as well.

\n\n\n\n

---\nconst { post } = Astro.props;\n---\n\n<article>\n    <a class='post-link' href={post.uri} aria-label={post.title}>\n        <h3>{post.title}</h3>    \n        <section>\n            <img src={post?.featuredImage?.node?.mediaItemUrl} alt=\"\">\n            <div>\n                <p set:html={post.excerpt}></p> \n                { post.categories.nodes.map(category => {\n                    return (<a class='term-link' href={category.uri}>{category.name}</a>)\n                })}\n                <span><time datetime={post.date}>{new Date(post.date).toLocaleDateString()}</time></span>\n            </div>\n        </section>\n    </a>\n</article>

\n\n\n\n

To access the post prop we passed into PostCard, we create a new variable in the component script and destructure our values from the Astro.props helper. As you can see, we liberally use the values of the current post in the template to construct the UI for this feature.

\n\n\n\n

In many instances with WordPress, you may want or need to inject HTML into an element, like is the case with the paragraph excerpt here:

\n\n\n\n

<p set:html={post.excerpt}></p>

\n\n\n\n

This set:html directive is a great example of one of the many template directives that Astro provides to make these things easier for developers.

\n\n\n\n

Additionally, if we look at other parts of this component, we see that we can even execute JavaScript expressions to render dynamic content on the fly. In this example, we format the date of our post to be more locale friendly:

\n\n\n\n

<time datetime={post.date}>{new Date(post.date).toLocaleDateString()}</time>

\n\n\n\n

As you can see, Astro components are pretty powerful on their own, which is one of the reasons why I chose to build this starter with them and not another framework. But with Astro you can have your dev cake, and eat it too since it supports all of the popular frameworks 🎂

\n\n\n\n

Now that we’ve seen what Astro components can do, let’s look at how we loaded the data from WordPress in the next step of this tutorial.

\n\n\n\n

Loading Data from WPGraphQL

\n\n\n\n

Astro itself is pretty unopinionated on how and where you fetch your data, but it does provide some helpful features: global fetch and top-level await.

\n\n\n\n

If we look again at these few lines of our component script, we can see at least one of those features at play. Since most of our data fetching should happen inside of a component script, we can just await async functions inside of the code fence.

\n\n\n\n

---\nimport { homePagePostsQuery } from \"../lib/api\";\n\nconst data = await homePagePostsQuery();\nconst posts = data.posts.nodes;\n---

\n\n\n\n

In these lines, we import homePagePostsQuery from an external file, call that function, and assign its return value to a variable for use inside of our template.

\n\n\n\n

Personally, I find this pattern really appealing for both its simplicity and its flexibility. This function behind the scenes can be a REST API call or GraphQL, and Astro doesn’t really care. We can also decide where this data fetching code lives.

\n\n\n\n

Do you want each component to fetch its own data? Cool, do that. Do you want to fetch all the data at the page component level and pass it via props? Awesome, have at it. Astro will let you be as simple or complex as your heart desires.

\n\n\n\n

In our case, we’re using WPGraphQL to fetch data, so let’s look at what our homePagePostsQuery function looks like under the hood:

\n\n\n\n

export async function homePagePostsQuery(){\n    const response = await fetch(import.meta.env.WORDPRESS_API_URL, {\n        method: 'post', \n        headers: {'Content-Type':'application/json'},\n        body: JSON.stringify({\n            query: `{\n                posts {\n                  nodes {\n                    date\n                    uri\n                    title\n                    commentCount\n                    excerpt\n                    categories {\n                      nodes {\n                        name\n                        uri\n                      }\n                    }\n                    featuredImage {\n                      node {\n                        mediaItemUrl\n                        altText\n                      }\n                    }\n                  }\n                }\n              }\n            `\n        })\n    });\n    const{ data } = await response.json();\n    return data;\n}

\n\n\n\n

Inside of this function, we’re doing some standard data fetching with fetch against our WPGraphQL endpoint. And, again, since this is meant to be a bland starter project, this code is intentionally vanilla and maybe not as DRY as it could be. From this starting point though, you could create a service that makes these fetch calls more elegant, or integrate other data fetching libraries like Apollo Client.

\n\n\n\n

Astro is still providing us with some nice scaffolding though. If you look at our data fetching file, you can see we are accessing our WORDPRESS_API_URL environment variable directly on import.meta.env.WORDPRESS_API_URL without having to install any packages or do any processing. This is Astro using Vite’s built in env variable support under the hood. While not a huge deal, it does remove on step from our workflow in creating a new site 🎉

\n\n\n\n

If you want to modify the query that we’re sending to WPGraphQL, the plugin installs a powerful GraphQL playground and query builder inside of your WordPress site.

\n\n\n\n

\n\n\n\n

I use this environment to develop new queries, test them against my live data, and as a reference when I’m using the data in my code. Now that we’ve got a good understanding of how the homepage works, let’s move on to looking at how Astro handles our dynamic content.

\n\n\n\n

Handling Dynamic Content

\n\n\n\n

In the previous examples we looked at, we rendered a mostly static page using Astro components and some data from WPGraphQL. But WordPress handles a number of different content types natively, like posts, pages, and categories, but also supports creating custom post types and custom fields that can be much more complex: like a space launch post type, for example 🚀

\n\n\n\n

So, how do we handle the dynamic content that WordPress can manage using Astro in a way that doesn’t get overly complicated?

\n\n\n\n

The answer is that we can actually lean into WordPress routing and templating conventions to simplify this for us.

\n\n\n\n

WordPress URIs and Routing

\n\n\n\n

Since WordPress core software serves both headless and non-headless use cases as a CMS, it already handles a lot of the leg work in defining routes as you naturally create your content. We can see some examples of typical route structures below:

\n\n\n\n

#Regular post route\n/awesome-astro-post\n\n#Hierarchical page route\n/parent/page-on-astro-feature\n\n#Category archive route\n/category/no-js-frameworks\n\n#Custome post type\n/spacelaunches/ma-8

\n\n\n\n

When creating headless WordPress sites, many developers end up reimplementing this routing structure in their frontend apps using various dynamic route pages and with multiple different queries across these routes.

\n\n\n\n

So, we might create routes like this in the Astro pages directory to handle displaying category archive pages:

\n\n\n\n

/pages\n     /category\n          /[categorySlug].astro

\n\n\n\n

As our content store grows to contain more post types or taxonomies, we have to reimplement frontend routes to handle those new content cases. But what if we could instead create a flexible catch-all route to handle all of the existing routes WordPress already knows about?

\n\n\n\n

That way, as we add content, we can focus mainly on the display of the content and less on the plumbing.

\n\n\n\n

By using the uri that WordPress assigns to each piece of content, we can simplify our apps to achieve some pretty cool workflows. To achieve this, we’re going to need to dig into how Astro handles dynamic routes.

\n\n\n\n

Astro and Dynamic Routing

\n\n\n\n

The way that Astro handles dynamic routing should look pretty similar to most meta-framework users, but by creating a file named with square brackets ([]), you create a dynamic route segment.

\n\n\n\n

So, inside of pages/category/[categorySlug].astro we can access that route parameter in our component script like this:

\n\n\n\n

---\nconst categorySlug = Astro.params.categorySlug;\n//do fetching for categories\n---

\n\n\n\n

While this is familiar, this only helps us fetch data for one particular content type, and doesn’t really support some of the hierarchical route examples we saw above: a parent -> child relationship between pages, for example.

\n\n\n\n

Luckily Astro gives us a mechanism to take more complicated paths as route params using rest parameters in our file name. Instead of creating a bunch of hardcoded routes, we create one route that will respond for all uris of any path depth.

\n\n\n\n

The file pages/[...uri].astro will then handle requests for any of our paths, and we will use that uri to query WordPress for the content. This catch-all pattern ends up being very flexible. Because of Astro’s route priority, the rest parameter route is evaluated last, which means that it’s easy to override if you want to create a specific route to match a content type.

\n\n\n\n

Now that we have a routing mechanism that can handle even our most complex uris, let’s look at how to incorporate that with WPGraphQL to query the data and Astro to render templates to HTML based on content type.

\n\n\n\n

Dynamic Content Templates in `[...uri].astro`

\n\n\n\n

Now that we have a conceptual understanding of WordPress uris and Astro route params, let’s look at how we can utilize these things in our Astro template:

\n\n\n\n

---\nimport MainLayout from \"../layouts/MainLayout.astro\";\nimport Archive from \"../components/templates/Archive.astro\";\nimport Single from \"../components/templates/Single.astro\";\nimport { getNodeByURI, getAllUris } from \"../lib/api\";\nconst uri = `/${Astro.params.uri}/`;\nconst data = await getNodeByURI(uri);\nconst node = data.nodeByUri;\n\nexport async function getStaticPaths(){\n    return await getAllUris();\n}\n\nfunction resolveContentTemplate(node){ \n    let template;\n    switch(node.__typename){\n        case 'Post':\n            template = Single;\n            break; \n        case 'Page':\n            template = Single;\n            break; \n        case 'Category':\n            template = Archive;\n            break; \n        case 'Tag':\n            template = Archive;\n            break; \n        default: \n            template = Single;\n    }\n\n    return template;\n}\n\nconst Template = resolveContentTemplate(node)\n\n---\n\n<MainLayout \n title={ node.title || node.name}\n description={ node.excerpt }\n>\n\t<main>\n        <Template node={node}></Template>\n\t</main>\n</MainLayout>\n

\n\n\n\n

There’s a lot going on in this code sample, so let’s spend some time looking at what’s going on here. First, you can see that this component script is much more robust than our previous examples, so let’s start by breaking out the data-fetching code.

\n\n\n\n

Data Fetching with `getNodeByUri`

\n\n\n\n

As we detailed in the previous section, this Astro component is going to catch all of our dynamic uris and then we’ll use those to query WordPress for the content:

\n\n\n\n

---\nimport { getNodeByURI, getAllUris } from \"../lib/api\";\nconst uri = `/${Astro.params.uri}/`;\nconst data = await getNodeByURI(uri);\nconst node = data.nodeByUri;\n---

\n\n\n\n

In this snippet, we import some of our data-related functions from an external file and again use the Astro.params helper to extract our uri param. For WordPress, we use a template literal to add slashes onto both ends of what Astro considers the uri. This just ensures they match when we request our data.

\n\n\n\n

From here we use that uri to make a particular GraphQL query that looks like this in lib/api.js:

\n\n\n\n

export async function getNodeByURI(uri){\n    const response = await fetch(import.meta.env.WORDPRESS_API_URL, {\n        method: 'post', \n        headers: {'Content-Type':'application/json'},\n        body: JSON.stringify({\n            query: `query GetNodeByURI($uri: String!) {\n                nodeByUri(uri: $uri) {\n                  __typename\n                  isContentNode\n                  isTermNode\n                  ... on Post {\n                    id\n                    title\n                    date\n                    uri\n                    excerpt\n                    content\n                    categories {\n                      nodes {\n                        name\n                        uri\n                      }\n                    }\n                    featuredImage {\n                      node {\n                        mediaItemUrl\n                        altText\n                      }\n                    }\n                  }\n                  ... on Page {\n                    id\n                    title\n                    uri\n                    date\n                    content\n                  }\n                  ... on Category {\n                    id\n                    name\n                    posts {\n                      nodes {\n                        date\n                        title\n                        excerpt\n                        uri\n                        categories {\n                          nodes {\n                            name\n                            uri\n                          }\n                        }\n                        featuredImage {\n                          node {\n                            altText\n                            mediaItemUrl\n                          }\n                        }\n                      }\n                    }\n                  }\n                }\n              }\n            `,\n            variables: {\n                uri: uri\n            }\n        })\n    });\n    const{ data } = await response.json();\n    return data;\n}

\n\n\n\n

This query can be kind of long to read, but is worth looking over a few times because its pretty much serves all of our data fetching needs across all our content types.

\n\n\n\n

The nodeByUri query in WPGraphQL is what facilitates most of this interaction. We pass a uri in as a variable, and then WPGraphQL queries all of the public nodes in your WordPress graph for that particular uri and then data for that particular node. This tutorial on the WPGraphQL site goes into more detail on this powerful pattern.

\n\n\n\n

But even though all our public content is accessible as a node type, the data we need for a category or author is different from the data we need for a post or page.

\n\n\n\n

This is where GraphQL fragments can help specify the data we need by type. For example, the following fragment tells WPGraphQL to return the specified data fields when the node that resolves to our uri is a Post type:

\n\n\n\n

                ` ... on Post {\n                    id\n                    title\n                    date\n                    uri\n                    excerpt\n                    content\n                    categories {\n                      nodes {\n                        name\n                        uri\n                      }\n                    }\n                    featuredImage {\n                      node {\n                        mediaItemUrl\n                        altText\n                      }\n                    }\n                  }`

\n\n\n\n

The code in the starter project contains fragments for Category, Post, and Page types, but could easily be modified to accommodate more types of content.

\n\n\n\n

Additonally, some developers choose to interpolate some of these fragments using template literals to keep the code a little bit more modular. But even without that, in about 80 lines of code we have a query powerful enough to power most basic use cases 🔥

\n\n\n\n

Now that we understand how Astro routing and WPGraphQL can work together to help you lean into WordPress CMS conventions, let’s round off our content templates.

\n\n\n\n

Rendering Static Content

\n\n\n\n

Astro has two primary methods for rendering you content: static or server rendered. This output method can be modified in the project config by adjusting the output, but for this tutorial we’ll assume you want to deploy your project statically.

\n\n\n\n

For Astro to build our project statically, it will need to know all of the possible routes for our dynamic route paths. Like Next.js dynamic Astro components rendering statically will need to export a getStaticPaths function that returns the paths as an array of objects:

\n\n\n\n

---\nexport async function getStaticPaths(){\n    return await getAllUris();\n}\n---

\n\n\n\n

While these few lines in our component script are fairly clean, the getAllUris does a bit more heavy lifting behind the scenes. The query itself isn’t interesting, but as we saw before we had to do some massaging to get Astro’s rest route params and WordPress’ uri to match.

\n\n\n\n

export async function getAllUris(){\n  const response = await fetch(import.meta.env.WORDPRESS_API_URL, {\n      method: 'post', \n      headers: {'Content-Type':'application/json'},\n      body: JSON.stringify({\n          query: `query GetAllUris {\n            terms {\n              nodes {\n                uri\n              }\n            }\n            posts(first: 100) {\n              nodes {\n                uri\n              }\n            }\n            pages(first: 100) {\n              nodes {\n                uri\n              }\n            }\n          }\n          `\n      })\n  });\n  const{ data } = await response.json();\n  const uris = Object.values(data)\n    .reduce(function(acc, currentValue){\n      return acc.concat(currentValue.nodes)\n    }, [])\n    .map(node => {\n      let trimmedURI = node.uri.substring(1);\n      trimmedURI = trimmedURI.substring(0, trimmedURI.length - 1)\n      return {params: {\n        uri: trimmedURI\n      }}\n    })\n\n  return uris;\n\n}

\n\n\n\n

To unpack most of this function, we make a call to WPGraphQL for all of the uris for the various content types we want. As you can see, we’re requesting the first 100 uris for each content type, which is the default limit for each query in WPGraphQL. You can manually adjust this value using a PHP filter or implement some sort of pagination if you have a lot of content.

\n\n\n\n

From there, we extract the top level properties using Object.values into an array, then reduce that array into one large array containing values from post, page, and category nodes. Finally, we map that combined array, trimming the beginning and ending slashes, and return an object for each path that is stuctured like this:

\n\n\n\n

      { \n        params: {\n           uri: trimmedURI\n        } \n      }

\n\n\n\n

This final array of the above formatted object is what we return in getStaticPaths so that Astro can build all of our uris. At this point, we can flexibly generate a page with Astro for all of the paths that WordPress manages 🚀

\n\n\n\n

Rendering the Content with Dynamic Templates

\n\n\n\n

Now that we have our content set to render statically with getStaticPaths and data available for each content node using the nodeByUri query, we can finally turn our attention to how this content gets presented visually.

\n\n\n\n

To refresh ourselves on what our catch-all page template looks like (with getStaticPaths removed for brevity):

\n\n\n\n

---\nimport MainLayout from \"../layouts/MainLayout.astro\";\nimport Archive from \"../components/templates/Archive.astro\";\nimport Single from \"../components/templates/Single.astro\";\nimport { getNodeByURI, getAllUris } from \"../lib/api\";\nconst uri = `/${Astro.params.uri}/`;\nconst data = await getNodeByURI(uri);\nconst node = data.nodeByUri;\n\nfunction resolveContentTemplate(node){ \n    let template;\n    switch(node.__typename){\n        case 'Post':\n            template = Single;\n            break; \n        case 'Page':\n            template = Single;\n            break; \n        case 'Category':\n            template = Archive;\n            break; \n        case 'Tag':\n            template = Archive;\n            break; \n        default: \n            template = Single;\n    }\n\n    return template;\n}\n\nconst Template = resolveContentTemplate(node)\n\n---\n\n<MainLayout \n title={ node.title || node.name}\n description={ node.excerpt }\n>\n\t<main>\n        <Template node={node}></Template>\n\t</main>\n</MainLayout>\n

\n\n\n\n

After we query WPGraphQL, we pass the resulting node into our resolveContentTemplate function, where a standard switch statement matches the node.__typename property to a particular content type.

\n\n\n\n

Once matched, we assign a particular Astro component import to a scoped template variable and then return that variable. Astro’s docs call these dynamic tags, and have a few caveats if you want to do this with anything that will require hydration:

\n\n\n\n

const Template = resolveContentTemplate(node)

\n\n\n\n

This dyanmic tag can then be used in the component template where we pass the node data in as a prop:

\n\n\n\n

<Template node={node}></Template>

\n\n\n\n

At this point, it’s really up to the developer to choose now to implement their templating rules if they want to use this convention.

\n\n\n\n

While traditional WordPress theme development is one of the reasons people choose a headless approach, lots of developers think fondly of the WordPress template hierarchy as a heuristic for organizing and prioritizing content rendering. It’s really cool to get to lean into the things WordPress does well while using JavaScript based tooling and components.

\n\n\n\n

Rendering `Single.astro`

\n\n\n\n

The last thing we’ll look at in our tour of this Astro starter is the content used for our single content types. The Single.astro component is rendered inside our catch-all route and takes our node variable as a prop:

\n\n\n\n

---\nconst { node } = Astro.props;\n--- \n\n <h1>{node.title}</h1>\n<!-- Display categories links if node has terms -->\n { node.categories ?\n    node.categories.nodes.map(category => (<a class='term-link' href={category.uri}>{category.name}</a>)) :     \n    null \n }\n<!-- Only show date if node is a Post -->\n {\n    node.__typename === 'Post' ? \n    (<p class='post-details'>\n        Posted on <time datetime={node.date}>{new Date(node.date).toLocaleDateString()}</time>\n    </p>):\n    null\n }\n <img class='featured-image' src={node.featuredImage?.node?.mediaItemUrl} alt=\"\">\n \n <article set:html={node.content}>\n </article>\n\n <style is:global>\n    .wp-block-image img {\n            width: 100%;\n            height: auto;  \n    }\n</style>\n<style>\n    img.featured-image {\n        width:100%;\n        border-radius:  10px;\n    }\n    .post-details {\n        color: darkgrey;\n        font-weight:300;\n    }\n    a.term-link {\n        display: inline-block;\n        height: 1.5rem;\n        padding: .75rem;\n        margin: .5rem .5rem .5rem 0;\n        background: linear-gradient(90deg,#0076dc 0%,#7a1ba6 100%);\n        color: #fff;\n        border-radius: 10px;\n        font-weight: bold;\n    }\n</style>\n

\n\n\n\n

We’ve touched on a lot of the conventions in here already, like Astro.props and set:html, but there are still a few things Astro has left to teach us about being an HTML developer 😎

\n\n\n\n

First, using the JSX-like syntax in Astro components, we can do some expressive conditional rendering in our templates:

\n\n\n\n

<!-- Only show date if node is a Post -->\n {\n    node.__typename === 'Post' ? \n    (<p class='post-details'>\n        Posted on <time datetime={node.date}>{new Date(node.date).toLocaleDateString()}</time>\n    </p>):\n    null\n }

\n\n\n\n

And we haven’t even touched on styling yet, but there is a lot to like about Astro here as well. As some who’s used single-file components a lot in Vue, I was excited to see Astro implement similar constructs in its components too. If you include a good old <style></style> tag in your Astro component, Astro will bundle those styles with your page and those styles will be scoped to that particular component. This makes it easy to write really clean and low-specificity CSS.

\n\n\n\n

However, there are a lot of instances where we need global styles, like when we need to target markup for an image returned from WordPress. Astro makes this particularly elegant, and instead of having a separate CSS file full of disconnected rules, you can add a directive to a style tag in your component file and apply the rules globally:

\n\n\n\n

 <article set:html={node.content}>\n </article>\n\n <style is:global>\n    .wp-block-image img {\n            width: 100%;\n            height: auto;  \n    }\n</style>

\n\n\n\n

In this example, we’re using the set:html directive to inject our CMS content into the article tag. Right below that we use the is:global directive on a style tag to add a global rule targeting the image markup contained in our WordPress content.

\n\n\n\n

Now that we have a good understanding of all of the pieces of our Astro project, let’s get this rocket off the ground and deploy this thing 👩‍🚀

\n\n\n\n

Deploying Astro Projects

\n\n\n\n

The Astro docs have a ton of guides that cover different deployment targets if you have a service in mind already. But since your reading a headless WordPress tutorial, I’ll show you how to set your project up to deploy on Atlas, our headless WordPress hosting platform.

\n\n\n\n

Since Astro builds output static assets, we’ll need to make two small changes to make it run inside of a Node container.

\n\n\n\n

First, we’ll add http-server as a dependency to our project and install if you want to run locally:

\n\n\n\n

$ npm install --save http-server

\n\n\n\n

With that project installed, we can tweak the start command to run that after building. Update the start script in package.json to look like this:

\n\n\n\n

\"start\": \"http-server ./dist\"

\n\n\n\n

Now, if you run the following commands locally Astro will build all of your paths statically, and then fire up a lightweight http server to serve those assets:

\n\n\n\n

$ npm run build && npm run start

\n\n\n\n

Wrapping Up

\n\n\n\n

Thanks for reading this far in the post. I’m really excited to share Astro with the headless WordPress community because I think the two technologies share a lot in common and pair so nicely together.

\n\n\n\n

Along with that, the Astro community itself is super inviting, so be sure to check out these resources to learn more about the awesome humans building this tool:

\n\n\n\n

\n","slug":"building-a-headless-wordpress-site-with-astro"},{"__typename":"Post","id":"cG9zdDo3Mjc=","slug":"wpgraphql-smart-cache-with-next-js-and-apollo","seo":{"__typename":"PostTypeSEO","readingTime":13},"title0":"WPGraphQL Smart Cache with Next.js and Apollo","uri":"/blog/wpgraphql-smart-cache-with-next-js-and-apollo/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo3","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/c24a68b84c9ad2b53c633d14917d8298?s=96&d=mm&r=g"},"name":"Francis Agulto","description":"---\r\ntitle: Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}}},{"__typename":"Post","id":"cG9zdDo3MTI=","slug":"seo-in-headless-wordpress-with-yoast-next-js-and-wpgraphql","seo":{"__typename":"PostTypeSEO","readingTime":10},"title0":"SEO in Headless WordPress with Yoast, Next.js and WPGraphQL","uri":"/blog/seo-in-headless-wordpress-with-yoast-next-js-and-wpgraphql/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo3","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/c24a68b84c9ad2b53c633d14917d8298?s=96&d=mm&r=g"},"name":"Francis Agulto","description":"---\r\ntitle: Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}}},{"__typename":"Post","id":"cG9zdDo2OTE=","seo":{"__typename":"PostTypeSEO","readingTime":9,"opengraphDescription":"In this article, I will discuss the topics and concepts that you will need to understand when considering and planning for Atlas as your Headless WordPress platform. Additionally, as you think about workflows, CI/CD, developer team structure, and developing on Atlas as a whole, I will go over several strategies and considerations that can help […]"},"uri":"/blog/planning-for-headless-wordpress-and-atlas/","title0":"Planning for Headless WordPress and Atlas","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo3","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/c24a68b84c9ad2b53c633d14917d8298?s=96&d=mm&r=g"},"name":"Francis Agulto","description":"---\r\ntitle: Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"date":"2022-10-18T18:57:15","content0":"\n

In this article, I will discuss the topics and concepts that you will need to understand when considering and planning for Atlas as your Headless WordPress platform. Additionally, as you think about workflows, CI/CD, developer team structure, and developing on Atlas as a whole, I will go over several strategies and considerations that can help guide you.

\n\n\n\n

If you have not yet tested or developed on Atlas, please access a free developer sandbox account here.

\n\n\n\n

If you are new to Headless WordPress or Atlas, please reference these guides: Atlas, Headless WordPress Roadmap

\n\n\n\n

Building a website in Headless WordPress

\n\n\n\n

The approach of building a Headless WordPress website is different from traditional WordPress in that Headless does not require that the requested data be created and then sent to the server to be processed. Rather, the data is pre-compiled and is made available to the browser through the Content Delivery Network, or CDN for short.

\n\n\n\n

This rendering begins with your modern JavaScript framework of choice pre-building your files (JavaScript, HTML, etc). It is important that the framework chosen supports static site generation, regardless of which rendering pattern you use. Once the files are generated, you can deploy them on the CDN.

\n\n\n\n

What this does is it removes the need for the browser to go through a long and time-consuming series of interactions between the server, database, and cache, improving the performance and speed of the website.

\n\n\n\n

In a traditional monolithic workflow, you have a developer writing code and programming the site. Then they ship it to the server where the server does the work of producing the HTML requested by the client and shipping that to the client. This is done upon every client-side request.

\n\n\n\n

One key decision in the planning of a Headless WordPress site is which files the developer chooses to generate at runtime versus generating them at build time. The decision to generate your files at build time or server-side rendering them at runtime may depend on several factors – how much content can be delivered statically, requirements for dynamic content (dynamic pages or smaller dynamic components, and performance needs).

\n\n\n\n

There is the flexibility of using different rendering patterns in Headless WordPress with your choice of a JavaScript framework, however, the foundation of the Jamstack or decoupled methodology is to pre-render as much content as possible during build time.

\n\n\n\n

Workflow Steps in using Atlas

\n\n\n\n

Here are the major line items you and your teams must decide when approaching a plan to build Headless WordPress on Atlas:

\n\n\n\n

Choose a front-end JS framework like Faust.js, Next.js, Vue, etc. Oftentimes this may be based on what you and your team are familiar with. Also consider some of the features of WordPress that the Publishers may require (post previews, sitemaps) and ensure the framework supports these.
Choose your WordPress API whether that is WP REST or WPGraphQL. Both can be used and if you need help deciding, please reference this article. If you have a preexisting WP install and want to migrate the data you can easily do so with the migration plugin via WP Engine.
Ensure your front-end code is in GitHub and is integrated with Atlas.
Create any Markdown files necessary on your front end and render the data to the files. This is outside any dynamic content to be rendered at runtime.
Lastly, push changes in GitHub and deploy to Atlas.

\n\n\n\n

Atlas Abstract: What it provides

\n\n\n\n

When you adopt Headless WordPress and choose Atlas, you not only get the Atlas platform, an ecosystem of defined tooling such as a CDN and infrastructure, but Atlas also supplies a lot of moving parts in the abstract. These layers that are abstracted allow developers to have a seamless workflow and experience without having to use multiple vendors, systems, etc. Let’s get into details on what Atlas provides and things you should consider.

\n\n\n\n

Continuous Integration/Continous Deployment

\n\n\n\n

One of the most difficult things you can do as a developer is to set up a build system and CI/CD pipeline. There is a lot of toil in this workflow that most developers do not want to do. This is why the emergence of services-hosted platforms, such as Atlas, has taken their place in the market. Fully managed, taking care of this all for you.

\n\n\n\n

The Atlas platform has a simple one-click connection to your Github making it painless to integrate with your repository.

\n\n\n\n

Other services (such as AWS) may allow you to select your own deployment zone, however, with Atlas, the CDN and the target are baked in. You are provided with everything you need to build and host your Headless site.

\n\n\n\n

Atlas’s build environment gives you a secure and customizable build step. When you build your app on Atlas, it will set up your environment and server, grab any needed dependencies, run the build and deploy. It supports all tooling, front-end frameworks, site generators, etc involved in building your site. You can customize your node and yarn versions, install dependencies, create custom build and start commands as well as trigger a build with webhooks from the WordPress backend should your content editors need it.

\n\n\n\n

Atlas CDN

\n\n\n\n

A content delivery network (CDN) is a group of servers that are distributed geographically and work together to provide fast and speedy delivery of internet content. Your assets such as your HTML pages, JavaScript files, stylesheets, images, and videos are quickly transferred onto a CDN for optimal access and performance to your users.

\n\n\n\n

A properly configured CDN may also help protect websites against some common malicious attacks, such as Distributed Denial of Service (DDOS) attacks.

\n\n\n\n

A CDN can’t replace the need for proper web hosting, but it does help cache content at the network edge, which improves website performance. Adding it to your website hosting helps optimize for performance.

\n\n\n\n

The CDN is a layer in your web tech stack that you must account for when you are in the planning phases of adopting Headless WordPress. Doing this ad-hoc and DIY can be time-consuming and tedious for the developer team. In order to alleviate this issue, Atlas does this for you out of the box.

\n\n\n\n

Atlas’s out-of-the-box CDN utilizes caching to reduce hosting bandwidth, helping to prevent interruptions in service, and improving security, and performance. A CDN, by nature, is distributed geographically which reduces the time it takes to get to your users. When you combine this with the approach of the Jamstack/decoupled architecture which prebuilds the markup, all those files become available statically on the CDN.

\n\n\n\n

In summary, the Atlas CDN provides:

\n\n\n\n

Improving website load times
Reduced bandwidth costs
Increased content availability and redundancy
Improved security

\n\n\n\n

WordPress APIs and 3rd Party APIs

\n\n\n\n

The next thing to consider in planning for the development of Headless WordPress is the WordPress install itself. Questions arise such as where to host it, which API you will use (WPGraphQL or REST), plugins, pairing environments with the JS frontend, and any customization to it.

\n\n\n\n

Even though a static Jamstack site can indeed be nothing more than a collection of static assets, connecting your application to your WP backend with the WPGraphQL or REST API is what shows the true power and promise of this as an architecture for real-world applications.

\n\n\n\n

This is the power and foundation behind the modular, decoupled, Jamstack approach. It gives frontend teams the power to not have to write any backend code. They can consume the WordPress data through an API endpoint, mainly REST or GraphQL.

\n\n\n\n

In fact, you’ll find many traditional players like Shopify, SalesForce, BigCommerce, GitHub, etc now offer APIs so they, too, can be consumed in a headless fashion. The explosion of APIs speaks to the momentum of the decoupled movement as the architecture of the interconnected web. As this API-driven development is becoming the norm, Atlas will support it.

\n\n\n\n

Once you decide what API you will use for WordPress, you will need a WordPress host for that install. On Atlas, you have a trusted WP hosting platform fully managed. You can rest assured that your WP install is kept secure, up to date, and given best-in-class maximum uptime as well as provisioning new WP installs with a simple click.

\n\n\n\n

FAQs/Best Practices 🌐 🤓

\n\n\n\n

Q: Can the size of a developer team affect the decisions on the kind of workflow implemented in Headless WordPress? (Large Agency/Small Independent Contractor)

\n\n\n\n

A: This is a subjective question because the size and number of a dev team are relative. However, for this article’s sake, let’s just say there can be a single one-person developer, a small dev team is about 2-5, and anything above 5 is mid to large.

\n\n\n\n

The main thing to consider here is your environments as far as development, staging, and production. If you have a large developer team that is pushing numerous changes to your code, it is a necessity to ensure those changes are exactly what you wanted before going live. Isolating these changes in environments solves this.

\n\n\n\n

A single developer can set up a simplified workflow with maybe only one or two environments, plus local. The Local Sites tool is great for a single developer workflow.

\n\n\n\n

When a development team is small to large, there are three things to consider when planning a workflow – 1) Everyone is able to contribute, 2) Everyone has access to the most recent versions, and 3) All developers are able to iterate through CI/CD.

\n\n\n\n

For larger agency teams, especially when developers are switching between projects, you might want to use a containerized approach where you can create a repeatable/cloned environment that each team member can use.

\n\n\n\n

Q: What if I want an efficient way to check my code on the browser without pushing it to production?

\n\n\n\n

Deployment previews in Atlas allow you to deploy a preview environment on a live URL without having to procure any isolated staging environment. It gives you a unique live site that is isolated off any feature branch you checkout. This will alleviate the issue of spinning up multiple staging environments and make your Atlas workflow better.

\n\n\n\n

Q: What are some recommendations for making sure your front & backend deploy at the same time?

\n\n\n\n

A: There are different ways you can approach the answer to this. For example, if you need to push changes to the WordPress backend to add and or remove functionality, and push changes to the frontend app synchronously to accommodate those backend changes, what is the best way to do so? 🤔

\n\n\n\n

Two main solutions that are most commonly used are:

\n\n\n\n

Push changes for the frontend & backend at the same time and don’t worry about the time variance. This would work for hobby sites, but not important ones where a page in an error state could mean an abandoned shopping cart, etc.
Include fallback code and do it in stages. Push code to the frontend and backend that tries to use the new changes, but gracefully falls back to the old version if it’s not available. This approach could use a feature flag, check for a certain version number, etc. Then once you’re confident all users are on the new version of the frontend application, push another update to finally remove the old functionality.

\n\n\n\n

One thing to note is that there really is no perfect solution to this question or any solution in Headless web development for that matter. The challenge of keeping your different code bases in sync from a timing perspective in this approach will have trade-offs on any option you choose and these are things that come with the territory. The key here is to just figure out which trade-offs mean more to you and your team.

\n\n\n\n

If you want a more granular example of these solutions to this question, we will have a deeper dive into it in an article to come soon!

\n\n\n\n

Let us know your thoughts!

\n\n\n\n

Feedback is golden on a product for developers. If there are any features that you want to see on Atlas and WordPress as a Headless CMS, please let us know! Drop us a line in our discord channel. Stoked!!! 🎉

\n","slug":"planning-for-headless-wordpress-and-atlas"},{"__typename":"Post","id":"cG9zdDo2NDU=","seo":{"__typename":"PostTypeSEO","readingTime":8,"opengraphDescription":"In this article, I will discuss the new Preview Environments and Webhook features in the Atlas platform. If you are new to Headless WordPress and would like to start testing out Atlas, sign up for a free sandbox account here! The Modern Developer Workflow Modern web developers using a git-based approach to development expect certain […]"},"uri":"/blog/atlas-platform-features-deployment-previews-webhooks/","title0":"Atlas Platform Features: Deployment Previews & Webhooks","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"$ref":"$[\"cache\"][\"posts1\"][\"nodes\"][0][\"author\"][\"node\"]"}},"date":"2022-09-20T15:23:02","content0":"\n

In this article, I will discuss the new Preview Environments and Webhook features in the Atlas platform. If you are new to Headless WordPress and would like to start testing out Atlas, sign up for a free sandbox account here!

\n\n\n\n

The Modern Developer Workflow

\n\n\n\n

Modern web developers using a git-based approach to development expect certain features and functionality on their hosting platforms, especially ones that support their CI/CD (Continuous Integration and Continuous Delivery) workflows.

\n\n\n\n

In the past, hosting platforms only allowed you to deploy sites to the same URL every time you pushed a change. If you wanted to test changes before making them live on your production site, you had to manually create new sites or environments with new URLs to preview those changes.

\n\n\n\n

For example, in some workflows, you may have testing or staging branches tied to specific environments, and committing to those branches could help you automatically preview your changes before merging them into production. While you can still do this with Atlas environments, this Git flow strategy may be too rigid for some teams or conflict with other philosophies on repository management.

\n\n\n\n

Luckily, the Atlas platform has a solution for this issue that makes CI/CD less tedious and more flexible to implement.

\n\n\n\n

Deployment Previews

\n\n\n\n

The Atlas team got me super stoked as we now have deployment previews!! This allows you and your team to see changes on your site without having to deploy them to your production site and without having to create a dedicated testing branch or environment.

\n\n\n\n

The value for the modern developer’s workflow is a less tedious, quicker way to enable better productivity. As a developer, this helps you achieve constant collaboration and iteration for a quicker “ship more and ship fast flow.”

\n\n\n\n

How Deployment Previews Work

\n\n\n\n

Deployment previews work by deploying every pull request from your GitHub repository to a specific preview environment, with its own URL, logging, and tools, in relation to the feature branch you created. This isolates each branch you make from your main production branch without having to manually spin up entirely new site environments!

\n\n\n\n

You and your team can view the unique URL to see how these changes look before they are merged into production and deployed.

\n\n\n\n

In order to enhance the workflow even more you can access information about the Atlas preview environment in two places: the GitHub UI and the Atlas Platform UI:

\n\n\n\n

\n\n\n\n

\n\n\n\n

You can link back and forth between UI’s conveniently as well.

\n\n\n\n

As you iterate and develop your site, you can continuously push multiple changes, checkout multiple branches, and share these URLs for collaboration and feedback, in turn exponentially increasing overall developer and team productivity. Under the hood, Atlas keeps up with your feature branch changes, builds the environment, and provides the unique URL! ⚡

\n\n\n\n

Please visit the preview environment docs for a step-by-step guide on usage.

\n\n\n\n

Deployment Previews FAQs

\n\n\n\n

I Don’t See Deployment Previews Anywhere in the Atlas Platform

\n\n\n\n

The deployment previews feature needs to be enabled on a per-environment basis, which means if you want to preview PRs submitted against your main or production branch, the setting needs to be enabled for that Atlas environment.

\n\n\n\n

Do Deployment Previews Count Towards My Resources?

\n\n\n\n

No, any deployment previews that you create do not count towards your plan entitlements.

\n\n\n\n

What Happens if I Make Additional Commits to a PR?

\n\n\n\n

If you continue to make commits to a feature branch with an open PR, Atlas will detect those changes and rebuild your deployment preview.

\n\n\n\n

How Do I Delete a Deployment Preview?

\n\n\n\n

The main mechanism for managing preview environments is the PR lifecycle. If you close a PR or merge it into its target branch, those actions will automatically delete the deployment preview associated with the PR.

\n\n\n\n

Atlas Environment Rebuild Webhooks

\n\n\n\n

The modern git-based workflow gets me JAMstoked because it enables quick continuous streamlined workflows with all things expected to be connected once things are spun up and pushed into your repository.

\n\n\n\n

Often times though, there are teams of content creators or other technical/non-technical stakeholders who are not immersed in the git-based flow but still need a way to push changes from the WordPress CMS to the front-end of their headless site. For example, if a site is using SSG, a content editor may want to rebuild a particular post or page whenever they update the resource in WordPress.

\n\n\n\n

What is a Webhook?

\n\n\n\n

This is where webhooks come into the workflow. A webhook is an HTTP-based callback function that allows lightweight, event-driven communication between two APIs.

\n\n\n\n

In this case, the WP Engine Atlas platform features webhooks that allow users to trigger an environment rebuild from an event created by WordPress. (e.g. updating, deleting, adding posts)

\n\n\n\n

Configuring Builds with Atlas Webhooks

\n\n\n\n

The Atlas platform makes it really easy to generate a webhook to rebuild your environment via WordPress events.

\n\n\n\n

Step 1: Go into your Atlas account and on to the Atlas accounts home page. Click on any app environment you choose:

\n\n\n\n

\n\n\n\n

Step 2: Once you choose an app environment and click on it, you will be taken to an environment settings page. Click on the Settings link:

\n\n\n\n

\n\n\n\n

Step 3: Clicking on the Settings link takes you to the Settings page. In the lower half of the page, you will see an Environment webhook pane. Click the Create a webhook button:

\n\n\n\n

\n\n\n\n

Once you click that, an endpoint will be generated like this:

\n\n\n\n

\n\n\n\n

Copy that endpoint URL because we are going to need it for our WordPress backend.

\n\n\n\n

Embed the Webhook in WordPress

\n\n\n\n

Now that your webhook is created on the Atlas platform, go into your WP Admin. From here, you can select a plugin that will help trigger your Atlas webhook based on an action you do in WordPress, such as adding a new post for example.

\n\n\n\n

You can use any plugin you like and we have some other suggestions in our docs, but in this example, I will use WP Webhooks.

\n\n\n\n

Go to the side menu of your WP Admin and hit Plugins > Add New and search for WP Webhooks. It should be the first one you see:

\n\n\n\n

\n\n\n\n

Once you install and activate the plugin, it will give you an option on the menu under Settings. Click on WP Webhooks there:

\n\n\n\n

\n\n\n\n

This will bring you to the WP Webhooks main page. In this case, we want to send data via a POST request to the Atlas platform when the webhook is triggered, so click on the Send Data option at the top:

\n\n\n\n

\n\n\n\n

Next, you will have options on what actions you want to associate with your webhook trigger. Let’s use Post updated. Once you choose the action, click on Add Webhook URL:

\n\n\n\n

\n\n\n\n

When you select those options, you will see a modal pop-up that will ask you to name your webhook and embed the webhook you created from Atlas:

\n\n\n\n

\n\n\n\n

And done!!! The next thing to do is go and create a new post. When you hit publish on that post, you can go to your Atlas account in WP Engine and see that a build was triggered due to the action in your WordPress backend!! Stoked! 🎉

\n\n\n\n

This feature here allows the modern web teams the ability to update data without having to touch code or jump into a command line.

\n\n\n\n

Please reference the docs as well for webhooks.

\n\n\n\n

Stay Tuned, more Atlas features to come…

\n\n\n\n

These two features are table stakes that modern jamstack/decoupled hosting platforms should have. The addition of these features to the Atlas platform will improve your modern web dev workflow across all your teams and stakeholders.

\n\n\n\n

Stay tuned for more Atlas features to come! As always let us know your feedback, thoughts, and ideas in Discord!

\n","slug":"atlas-platform-features-deployment-previews-webhooks"},{"__typename":"Post","id":"cG9zdDo2NTE=","seo":{"__typename":"PostTypeSEO","readingTime":6,"opengraphDescription":"In this post, we'll look at some of the best headless eCommerce platforms that you can use with your headless WordPress sites."},"uri":"/blog/best-headless-ecommerce-platforms-for-wordpress/","title0":"Best Headless eCommerce Platforms for WordPress","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMg==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/a64abda82041a00e479ecc2b156d7947?s=96&d=mm&r=g"},"name":"Jeff Everhart","description":"---\r\ntitle: Sr. Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"date":"2022-09-12T14:51:01","content0":"\n

The movement toward headless or decoupled sites involves giving site builders freedom to use the platforms and tools they already have, instead of locking them into an ecosystem that won’t evolve with their development practices. When talking to developers considering switching to a headless eCommerce platform as a solution to specific problems with monolithic or traditional eCommerce sites, here are a few things they mention:

\n\n\n\n

All-in-one eCommerce Platforms Lack Key Features

\n\n\n\n

If you have a traditional eCommerce site, and it doesn’t manage your content marketing collateral effectively, headless eCommerce patterns allow you to integrate other headless CMSs that do a better job of creating and managing content.

\n\n\n\n

API-driven Development of Headless eCommerce Enables Flexibility

\n\n\n\n

If your business or organization has unique requirements, such as offering products for both wholesale and retail or supporting multiple storefronts, it may be easier to support those use cases with the API-driven development patterns that headless eCommerce enables. In addition, API-driven commerce can more easily enable sales in non-standard channels, such as in-game transactions or AR/VR environments.

\n\n\n\n

Headless eCommerce Offers Total Control over the Site Experience

\n\n\n\n

While all-in-one eCommerce solutions can be great for getting a small business up and running quickly, at a certain scale, online sellers may need more control over the site experience than all-in-one platforms can provide. Whether the goal is increased speed, scalability, performance, or improved aesthetics, a headless approach can provide more granular control over these aspects of your eCommerce site. Anecdotally, this is what we see from larger brands and stores that want a higher degree of control than any all-in-one platform can offer.

\n\n\n\n

Choosing a Headless eCommerce Platform

\n\n\n\n

With an increased interest in headless eCommerce, it’s no surprise that both existing and new companies are creating solutions to fill this demand. As a part of our own research into the space, the WP Engine headless developer relations teams spent some time looking at the most popular headless eCommerce platforms. This list isn’t exhaustive, so if you think there is a service missing from this list, please let us know so we can add it to the roundup. We’ll do our best to keep this list updated with the latest features as these platforms grow and evolve.

\n\n\n\n

BigCommerce

\n\n\n\n

BigCommerce provides a variety of eCommerce solutions, and headless eCommerce is one of those features. There is already a Vercel/Next.js integration with BigCommerce. The BigCommerce platform has fairly robust documentation for its REST APIs, and it looks like they are in the process of building new APIs using GraphQL. The platform also offers a service for generating webhooks based on certain events.

\n\n\n\n

Shopify

\n\n\n\n

Shopify is one of the largest players in eCommerce and will likely be the most well-known name on this list. It advertises headless options as a part of its Plus offering and overall has a long reputation of being friendly to developers. Headless commerce is enabled on the platform using a number of different APIs. The Admin API offers features in both REST and GraphQL, while the Storefront API offers developers a GraphQL API that they can use with a number of different SDKs, including Node.js and PHP.

\n\n\n\n

But Shopify also provides a JavaScript-based framework called Hydrogen that provides a lot of out-of-the-box configuration and scaffolding for developers looking to use React. If you’re building apps or integrating with other services, there are webhooks you can tap into as well.

\n\n\n\n

Swell

\n\n\n\n

Swell is an API-first, as opposed to API-only, service for modern eCommerce. The Swell platform provides developers with backend and storefront REST APIs to create both custom administrative back-office experiences as well as custom storefronts. In addition to these headless features, Swell also has a system of events and webhooks that developers can use to run custom business logic based on platform events.

\n\n\n\n

Since Swell is API-first and not API-only, it also provides some of the traditional tools you might expect with other eCommerce platforms, like a visual shop builder and admin interfaces to manage data, but also a hosted checkout page in case developers want to offload this portion of development to the platform. A GraphQL API appears to be in beta.

\n\n\n\n

CommerceLayer

\n\n\n\n

CommerceLayer bills itself as a composable commerce API for developers, and this developer-centric positioning is apparent both on its website and in its onboarding process, which asks you to create inventory and run a test purchase all via CLI commands 🤯

\n\n\n\n

In addition to 400+ REST API endpoints, the platform also offers real-time webhooks and a few dozen integrations with other platforms. While it is positioned primarily as an API tool, it includes hosted checkout pages and carts, as well as an admin interface to manage back-office data.

\n\n\n\n

Commerce.js

\n\n\n\n

Commerce.js is an API-first platform that offers an admin dashboard along with a set of robust commerce APIs, as well as some hosted checkout features. The REST API endpoints have a lot of documentation and a JavaScript SDK to make building applications easier. In addition, Swell has curated some framework-based starter applications that developers can use to get up and running quickly in their favorite framework. The platform also has a list of events that can generate webhooks.

\n\n\n\n

One intriguing feature of Commerce.js is its positioning around alternative methods of payment and varying points of sale, advertising things like payment via Crypto gateway or with a QR code and taking payments inside of video games or from IoT devices. Some of that is likely possible on other commerce platforms, but it is interesting to see it highlighted like this on the Commerce.js platform because it really speaks to where eCommerce is headed.

\n\n\n\n

Snipcart

\n\n\n\n

Snipcart allows you to easily add a shopping cart to an existing website and is built around facilitating commerce using Jamstack approaches to development. It provides a robust suite of tools for sellers and offers a quick and easy JavaScript integration. If you are looking to create commerce functionality in an existing JavaScript application, you can use their JavaScript SDK, but they offer a robust REST API as well if you want to integrate with another backend service or write your own integration with your front-end site. Like many other platforms, Snipcart offers event-based webhooks and has a number of community-supported integrations.

\n\n\n\n

WooCommerce

\n\n\n\n

As a WordPress-focused company, we can’t talk about headless eCommerce without mentioning WooCommerce. WooCommerce is a plugin-based add-on that turns WordPress itself into a commerce engine. For most WooCommerce users, this means WordPress gets used in a traditional or monolithic way, but WooCommerce also enables headless development using both core features and additional plugins. For example, WooCommerce extends WordPress’ REST API, which allows developers to integrate with WooCommerce in a variety of creative ways. If you’re looking to use GraphQL, WPGraphQL has a community-supported add-on for WooCommerce that should enable that. WooCommerce comes with a lot of built-in tools for inventory & commerce management, but also includes a system of webhooks as a part of the API.

\n\n\n\n

Comparison Table

\n\n\n\n

	Management UI	REST API	GraphQL API	Webhooks	Hosted Store Components
BigCommerce	✅	✅	Early Release	✅	✅
Shopify	✅	✅	✅	✅	✅
Swell	✅	✅	Beta	✅	✅
CommerceLayer	✅	✅	❌	✅	✅
Commerce.js	✅	✅	❌	✅	✅
Snipcart	✅	✅	❌	✅	✅
WooCommerce	✅	✅	✅	✅	✅

\n\n\n\n

This table was last updated on 09/12/2022. If you believe something has changed on one of these platforms, please let us know.

\n\n\n\n

Did We Miss Anything?

\n\n\n\n

If you think that we need to add another eCommerce platform to the list, feel free to let us know on Twitter or through our Discord. We are always interested in growing the list of tools we can recommend or hearing about the cool things you’ve been building.

\n\n\n\n

\n","slug":"best-headless-ecommerce-platforms-for-wordpress"}],"pageInfo":{"__typename":"WPPageInfo","hasNextPage":true,"endCursor":"YXJyYXljb25uZWN0aW9uOjY1MQ=="}}},"selections":[[["0-1-2","posts0"],["3-4-5","avatar0"],["6-4-7","title0"],["8-9-10","post0"],["11-4-7","content0"],["8-12-10","post1"],["8-13-10","post2"],["8-14-10","post3"],["8-15-10","post4"],["8-16-10","post5"],["8-17-10","post6"],["8-18-10","post7"],["8-19-10","post8"],["8-20-10","post9"],["8-21-10","post10"],["8-22-10","post11"],["8-23-10","post12"],["8-24-10","post13"],["8-25-10","post14"],["8-26-10","post15"],["8-27-10","post16"],["8-28-10","post17"],["8-29-10","post18"],["0-30-2","posts1"],["8-31-10","post19"],["8-32-10","post20"],["33-34-35","headlessWordPressPlugins0"]],[["posts",0],["{\"first\":3}",1],["{\"after\":\"String\",\"before\":\"String\",\"first\":\"Int\",\"last\":\"Int\",\"where\":\"RootQueryToPostConnectionWhereArgs\"}",2],["avatar",3],["{}",4],["{\"forceDefault\":\"Boolean\",\"rating\":\"AvatarRatingEnum\",\"size\":\"Int\"}",5],["title",6],["{\"format\":\"PostObjectFieldFormatEnum\"}",7],["post",8],["{\"id\":\"work-with-gravity-forms-in-headless-wordpress\",\"idType\":\"SLUG\"}",9],["{\"asPreview\":\"Boolean\",\"id\":\"ID!\",\"idType\":\"PostIdType\"}",10],["content",11],["{\"id\":\"best-headless-ecommerce-platforms-for-wordpress\",\"idType\":\"SLUG\"}",12],["{\"id\":\"atlas-platform-features-deployment-previews-webhooks\",\"idType\":\"SLUG\"}",13],["{\"id\":\"planning-for-headless-wordpress-and-atlas\",\"idType\":\"SLUG\"}",14],["{\"id\":\"multilingual-headlesswordpress-with-nextjs-wpgraphql-polylang\",\"idType\":\"SLUG\"}",15],["{\"id\":\"crash-course-build-a-simple-headless-wordpress-app-with-next-js-wpgraphql\",\"idType\":\"SLUG\"}",16],["{\"id\":\"what-is-headless-wordpress\",\"idType\":\"SLUG\"}",17],["{\"id\":\"atlas-content-modeler-walk-through\",\"idType\":\"SLUG\"}",18],["{\"id\":\"state-of-headless-development\",\"idType\":\"SLUG\"}",19],["{\"id\":\"custom-content-types-in-headless-wordpress\",\"idType\":\"SLUG\"}",20],["{\"id\":\"headless-wordpress-with-vue-and-nuxt-js\",\"idType\":\"SLUG\"}",21],["{\"id\":\"the-when-and-where-of-rendering\",\"idType\":\"SLUG\"}",22],["{\"id\":\"when-should-i-use-headless-wordpress\",\"idType\":\"SLUG\"}",23],["{\"id\":\"headless-wordpress-tech-stack-options\",\"idType\":\"SLUG\"}",24],["{\"id\":\"what-is-atlas-content-modeler\",\"idType\":\"SLUG\"}",25],["{\"id\":\"rendering-patterns-in-headless-wordpress\",\"idType\":\"SLUG\"}",26],["{\"id\":\"efficient-ssg-in-next-js-with-wpgraphql\",\"idType\":\"SLUG\"}",27],["{\"id\":\"introduction-to-graphql-in-wordpress\",\"idType\":\"SLUG\"}",28],["{\"id\":\"building-a-headless-wordpress-site-with-astro\",\"idType\":\"SLUG\"}",29],["{\"first\":9}",30],["{\"id\":\"what-is-headless\",\"idType\":\"SLUG\"}",31],["{\"id\":\"gutenberg-in-headless-wordpress-wpgraphql-gutenberg\",\"idType\":\"SLUG\"}",32],["headlessWordPressPlugins",33],["{\"first\":500}",34],["{\"after\":\"String\",\"before\":\"String\",\"first\":\"Int\",\"last\":\"Int\",\"where\":\"RootQueryToHeadlessWordPressPluginConnectionWhereArgs\"}",35]],[[0,1],[3,0],[6,0],[8,20],[11,0],[33,0]],"v0"]}

What is Astro?

Getting Started with the WordPress CMS

Getting Started with Astro

Astro and File-based Routing

Building a Homepage

Loading Data from WPGraphQL

Handling Dynamic Content

WordPress URIs and Routing

Astro and Dynamic Routing

Dynamic Content Templates in [...uri].astro

Data Fetching with getNodeByUri

Rendering Static Content

Rendering the Content with Dynamic Templates

Rendering Single.astro

Deploying Astro Projects

Wrapping Up

Building a website in Headless WordPress

Workflow Steps in using Atlas

Atlas Abstract: What it provides

Continuous Integration/Continous Deployment

Atlas CDN

WordPress APIs and 3rd Party APIs

FAQs/Best Practices 🌐 🤓

Q: Can the size of a developer team affect the decisions on the kind of workflow implemented in Headless WordPress? (Large Agency/Small Independent Contractor)

Q: What if I want an efficient way to check my code on the browser without pushing it to production?

Q: What are some recommendations for making sure your front & backend deploy at the same time?

Let us know your thoughts!

The Modern Developer Workflow

Deployment Previews

How Deployment Previews Work

Deployment Previews FAQs

I Don’t See Deployment Previews Anywhere in the Atlas Platform

Do Deployment Previews Count Towards My Resources?

What Happens if I Make Additional Commits to a PR?

How Do I Delete a Deployment Preview?

Atlas Environment Rebuild Webhooks

What is a Webhook?

Configuring Builds with Atlas Webhooks

Embed the Webhook in WordPress

Stay Tuned, more Atlas features to come…

All-in-one eCommerce Platforms Lack Key Features

API-driven Development of Headless eCommerce Enables Flexibility

Headless eCommerce Offers Total Control over the Site Experience

Choosing a Headless eCommerce Platform

BigCommerce

Shopify

Swell

CommerceLayer

Commerce.js

Snipcart

WooCommerce

Comparison Table

Did We Miss Anything?

Dynamic Content Templates in `[...uri].astro`

Data Fetching with `getNodeByUri`

Rendering `Single.astro`

Blog