{"cache":{"posts1":{"__typename":"RootQueryToPostConnection","nodes":[{"__typename":"Post","id":"cG9zdDozMjA=","uri":"/the-when-and-where-of-rendering/","seo":{"__typename":"PostTypeSEO","readingTime":9,"title":"The When and Where of Rendering - WP Engine Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo4","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/999d8bf58fa6790945f2aff83a31c3df?s=96&d=mm&r=g"},"name":"Alex Moon","description":"---\r\ntitle: Solutions Architect\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"title0":"The When and Where of Rendering","slug":"the-when-and-where-of-rendering","content0":"\n

I recently had a deep discussion on a GitHub RFC about what to call a rendering pattern and was very confused about the other person’s perspective. I have a degree in Ancient Greek, so I tend to be particular about language and how folks define things. I argued that what they were giving this fancy name was actually just server-side rendering(SSR). They were emphatic it was not. I was being pedantic; but also trying to understand. They finally said something that made me realize we were looking at this from two different but equally valid perspectives.

\n\n\n\n

I was looking at the where of rendering. Does it happen on the build server(SSG), on the runtime server(SSR), or the client(CSR)? They looking at it from a perspective of when it was rendered. Did it happen during the build, when the server received a request from a user’s browser, etc? Because we were looking at it from a different perspective, how we named it would be different.

\n\n\n\n

This conversation made me realize the traditional rendering methods (SSG, SSR, and CSR) have become an oversimplification of a much more complex issue. Some of what we’ll be talking about might seem pedantic at first, maybe it is, but in the end, I believe it will allow us to think about rendering in a much more nuanced way.

\n\n\n\n

Define “render”…

\n\n\n\n

Technically all sites are “rendered” from CSS, HTML, JS, images, Wasm, JSON, XML, etc. in the browser. While a good definition, it’s not helpful for our purposes. The “R” of SSR is why I choose the word “render”. “Generate” as in Static Site Generator(SSG) might be a better term, but I think the industry settled on “render” a long time ago, so here we are.

\n\n\n\n

A site is “rendered” when the finalized form of the content is generated. But what IS content? HTML, CSS, images, videos, etc? All those different file types are critical, but there’s only one kind of content any website MUST have.

\n\n\n\n

HTML.

\n\n\n\n

When your browser does that first HTTP GET request, it’s not asking for an image, XML, or anything else. It wants that HTML goodness. From the HTML, our fonts, scripts, styles, and images can be loaded by the browser, but the HTML is the basis for all web pages.

\n\n\n\n

Your website is “rendered” when the HTML content is finalized.

\n\n\n\n

Where?

\n\n\n\n

We’ll start with the where of rendering. There are four locations where content may be rendered: the code editor, the build server, the runtime server, or the client (e.g., browser).

\n\n\n\n

Did you type out your HTML? Not just a template, but all the content and data directly? Great! You’ve rendered your site in your code editor.

\n\n\n\n

Did you create templates and merge the data on a build server (your local computer counts) to generate pages for each of your routes? Then you’ve rendered on the build server.

\n\n\n\n

Did you write code that allows users to be served unique pages based on permissions, queries, routes, etc.? Then your site is rendered on the server!

\n\n\n\n

Did you write a basic HTML file that all routes share, and you use JavaScript in the browser to render elements of HTML and fetch data based on their permissions, queries, route, etc? Then you’ve generated the final HTML on the client!

\n\n\n\n

Hopefully, this makes sense, and don’t worry; we’ll give relevance and talk more in-depth about these soon.

\n\n\n\n

When?

\n\n\n\n

The when of rendering is more…complicated. But let’s start with the examples above.

\n\n\n\n

If you rendered your site in an editor, the when would be called “author time.” But you can’t not write something when you write something. This distinction is pedantic. For the sake of this discussion, “Author Time Rendering” doesn’t matter because it is uniquely tied to its where. Let’s forget about it and focus on all computer-based rendering methods.

\n\n\n\n

If you render something on a build server(SSG), this could be done when you trigger the task manually, via webhook, via git merge, etc. Any number of events can trigger a build on a server.

\n\n\n\n

If you have code running on a runtime server(SSR) it traditionally renders on receipt of an HTTP request.

\n\n\n\n

Finally, client-side rendering (CSR) is done when the page is loaded or upon a user event such as a button click or page scroll. I hope the client-side is well understood, I’m not going to get much into this here.

\n\n\n\n

The future of rendering

\n\n\n\n

I won’t speak for everyone, but for myself, I’ve always (incorrectly) thought of rendering as a very black and white thing. I can have SSG, SSR, or CSR (client-side). Traditionally this has been true, but with new technology has come new possibilities. We need to recognize these names only describe the where of rendering.

\n\n\n\n

The future of rendering has to happen in one of these three places. But, by playing with when they happen, or even combining strategies, we can create some really great new patterns to further expand what’s possible in web development. Let’s talk about how this has already started to happen.

\n\n\n\n

Hybrid rendering

\n\n\n\n

Hybrid rendering isn’t a new space. Gatsby, Next, Nuxt, and others have been doing this for years at this point. But not everyone realizes this, so I’ll give a quick overview.

\n\n\n\n

Let’s imagine we have a page with some user interface element that allows them to load additional content. The user navigates to the page. How did the initial HTML get to the browser? Was it just shipped from a static file? Generated by a server? Written to the DOM by JS? Well, what did the button do? Was the HTML already in the browser, and the JS modified the CSS classes to show the content? Or did it fetch data from an API and add HTML?

\n\n\n\n

For this exercise, let’s presume the site was built with an SSG. Then some JS loads specific data from an API upon the user action. In this case, we have a site mainly generated on the build server, but a small part was rendered on the client. I’d call this hybrid rendering, specifically SSG + CSR. Gatsby and Next can statically build most of your site and fetch the dynamic bits on the client, automatically or by user action. React Hydration helps enable this.

\n\n\n\n

This pattern lets us build more app-like experiences that require heavy client-side code. But solve the SPA problem of not pre-rendering anything. It gives us the performance benefits of SSG, with the flexibility of a SPA.

\n\n\n\n

Build time

\n\n\n\n

Build server rendering is an exciting space right now. Netlify and the Jamstack have helped drive innovation here over the last ~5 years or so. Two big cases stand out to me. Netlify’s own DPR, and Gatsby Cloud’s Incremental Builds. Both of these platforms serve content from static file hosting (s3 bucket). In DPR’s case (if I understand it correctly), a route that doesn’t exist triggers a build, but cloud magic happens since there is no runtime server, and a build server generates that page. In the case of Gatsby Cloud, the request can’t create a build like in the case of DPR, but a webhook event due to a data change or code change triggers a build. Gatsby’s internals goes to work, figure out what’s needed, and you get a new page.

\n\n\n\n

It’s SSG! It’s SSR! No, it’s ISR/DSG/DPR, aka “the new hotness”!

\n\n\n\n

5+ years ago, the only when an SSG had access to was “build time.” With the advent of the Jamstack, Gatsby, Netlify, and headless CMSes we started connecting the CMS to our build pipelines. Maybe it’s been longer, I won’t pretend that 5 years isn’t a guess. My point is this only somewhat recently became common, and mainstream. The fundamental issue with SSG is the time it takes to build the site. Small sites are fine, but you try to generate 100s or 1000s of pages and your build times shoot through the roof to the dismay of content publishers (silly publishers, only if devs didn’t have to deal with them we could have perfect tech 😝). Gatsby and others have pioneered features like incremental builds to accelerate the build process, but a lot of cloud magic isn’t necessarily available unless you buy their products.

\n\n\n\n

This “build time” issue brought the Jamstack world back to Next and SSR. Yes, static files were fast, and atomic deploys were nice. But we’ve been scaling server-side apps for 2+ decades now since the advent of PHP and ASPX. It’s easy! (spoiler, it’s not). But you’re fighting physics when you have to process and render HTML on the server vs loading it from a CDN. We’re stuck, both methods have benefits and drawbacks. How do we solve these problems?

\n\n\n\n

Next solved this by shipping Incremental Static Regeneration. Which, despite the word “static” in the title, and some other limitations, it’s SSR + a stale-while-revalidate (SWR) cache to allow deferring the rendering from build time to later. Next’s ISR has its issues, but I think it’s the first in a new era of rendering patterns.

\n\n\n\n

The genius of ISR is that it took the SSG technology in Next, shipped it to the server, and put it behind an SWR cache. This means Next is not doing “SSG” on your site. The build step packages up available routes and JS/CSS files but the actual HTML render is on the server. It’s actually SSR. But, instead of rendering on every request, it only renders on the first request, and subsequently after the cache has been invalidated by a timeout.

\n\n\n\n

Next has taken the traditional idea of where of SSR and modified it’s traditional when from being on every request, to only when the cache is invalidated. Genius.

\n\n\n\n

Gatsby

\n\n\n\n

Gatsby just announced some very exciting features: Deferred Static Generation(DSG), and Server Side Rendering(SSR). SSR is exactly as it seems. The request comes in, content is fetched, a page is rendered, the response is sent. Nothing unique, but cool that Gatsby is supporting this.

\n\n\n\n

DSG is what we really need to talk about. You may be wondering, is this like Next’s ISR? The answer is, kinda, but different. I’d say, better. For context, Gatsby’s defining feature is its GraphQL data layer. This allows Gatsby to know everything about your site and what content is on what page. This enables some cool things.

\n\n\n\n

So, for DSG, just like ISR, a deferred page is not built at build time. Instead, it’s, wait for it, deferred. When the first request comes in for a page its data is fetched from the data layer and the HTML is rendered. That is cached and subsequent responses should be from a cache. Sounds a lot like ISR, right? Well, this is where the similarities end.

\n\n\n\n

Because Gatsby knows where every piece of content is on your site, when it receives a notification(usually a webhook) that data has changed, it can invalidate all the routes that use that data. This has a huge win over time-based cache invalidation because while one route might never be updated, another might get updates every 2 minutes. Both will be invalidated only when the rebuild is required.

\n\n\n\n

Gatsby has taken SSR and modified the when to be when the data populating the page is changed.

\n\n\n\n

Conclusion

\n\n\n\n

It’ll be cool to see where we are with rendering patterns and the web in another couple of years and how much more scalable and flexible our frameworks become. Request time SSR is great and has its place. But I’m really looking forward to seeing how we can continue to scale “static” site generators to enable a more performant web.

\n"},{"__typename":"Post","id":"cG9zdDoyOTY=","uri":"/atlas-content-modeler-walk-through/","seo":{"__typename":"PostTypeSEO","readingTime":17,"title":"Atlas Content Modeler Walk-Through - WP Engine Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}}}},"title0":"Atlas Content Modeler Walk-Through","slug":"atlas-content-modeler-walk-through","content0":"\n

In my recent “What is Atlas Content Modeler?” blog post, I described Atlas Content Modeler (ACM) as a single tool that allows you to create content models and expose them in the WPGraphQL/REST API schema– something that previously required cobbling together several other plugins.

\n\n\n\n

In this post, we’ll walk through all the features that ACM brings to the table, including the new Taxonomy and Relationships features. We’ll see how we can easily build our content models in the WordPress admin, then see an example Next.js app that consumes the data those models provide and uses it to render the pages of our app.

\n\n\n\n

What We’ll Build

\n\n\n\n

To showcase ACM’s superpowers, we’re going to build the most exciting app imaginable:

\n\n\n\n

🎉 A Healthcare Provider Registry! 🎉 🙃

\n\n\n\n

We’ll use ACM to create the content models we need in WordPress, then we’ll query for that data from a decoupled frontend Next.js app.

\n\n\n\n

First things first. Let’s set the scene. 🌆

\n\n\n\n

We’ve been tasked with building a web app that provides a listing of healthcare professionals. It needs to display a number of details about each provider including the locations where they practice.

\n\n\n\n

In our talks with the client, we’ve learned that the following three types of pages are required for the minimum viable product:

\n\n\n\n

Content Models

\n\n\n\n

Now that we know what pages need to exist in the frontend of our app, we need to think about what content models we need to create to store the necessary data. After some deliberation, we come up with these:

\n\n\n\n

Provider

\n\n\n\n

Name – Text field. The person’s name.
Credentials – Text Field (MD or DO, for example)
Profile Photo – Media Field.
Bio – Rich Text field. This is a blurb about the provider.
Practicing Since – Number field. This is the year the provider began practicing medicine.
Locations – Relationship field. These relationships between Provider → Locations represent the locations where the provider practices.
Specialty – Taxonomy. These taxonomy terms represent the provider’s specialties (Emergency Medicine, Pediatrics, etc.).

\n\n\n\n

Location

\n\n\n\n

Name – The name of the location.
Description – A description of the location.
Photo – A photo of the location.

\n\n\n\n

Now that we have our game plan together for what pages we’ll need and what content models we’ll need to set up in Atlas Content Modeler, let’s hop to it!

\n\n\n\n

Create Content Models

\n\n\n\n

If you’d like to follow along, you can spin up a new local WordPress site, then install and activate the WPGraphQL and Atlas Content Modeler plugins.

\n\n\n\n

Let’s create our Location model first, since it’s a bit simpler.

\n\n\n\n

Location Model

\n\n\n\n

In the WordPress admin sidebar, we’ll go to Content Modeler > Models and click the button to create a new model.

\n\n\n\n

We’ll fill out the fields as follows:

\n\n\n\n

Give the model a Singular Name of “Location” and a Plural Name of “Locations”.
Stick with the auto-generated Model ID of “location”.
Set the API Visibility to “Public” so we’ll be able to query for Location data from our decoupled JS app.
Select a Model Icon.
Enter a Description for the model.

\n\n\n\n

\n\n\n\n

Then click the button to create the new model.

\n\n\n\n

In the WordPress admin sidebar, you’ll see that a menu item has been added for our new Location custom post type.

\n\n\n\n

Location Model Fields

\n\n\n\n

Hit the + button to add a new field to our Location model.

\n\n\n\n

Fist, let’s create the Name field to store the name of each location. We’ll set the field up like this:

\n\n\n\n

Select Text for the type of field.
Enter a Name of “Name”.
Stick with the auto-generated API Identifier of “name”.
Select an Input Type of “Single line”.

\n\n\n\n

\n\n\n\n

Then click the button to create the field.

\n\n\n\n

We’ll create the Description and Photo fields in a similar fashion. They’ll end up looking like this:

\n\n\n\n

Description:

\n\n\n\n

Type of field: Rich Text.
Name: “Description”.
API Identifier: “description”.

\n\n\n\n

\n\n\n\n

Photo:

\n\n\n\n

Type of field: Media.
Name: “Photo”.
API Identifier: “photo”.

\n\n\n\n

\n\n\n\n

That’s it in terms of fields for our Location model.

\n\n\n\n

Next let’s see how our content creators can create and edit Location data. From the WordPress admin sidebar, go to Locations > Add New. You’ll see the fields we registered reflected here.

\n\n\n\n

\n\n\n\n

Go ahead and create a few dummy Location posts so we’ll have some data to work with.

\n\n\n\n

Location Model Query

\n\n\n\n

At this point, our Location model and its fields have been created, and ACM has automatically added them to the GraphQL schema for us. This means that things are already set up for us to query for Location data from our decoupled frontend JS app! Next let’s fire off a test query to try that out.

\n\n\n\n

Head back to the Content Modeler > Models page.

\n\n\n\n

Click the ... icon next to our Location model, then click Open in GraphiQL.

\n\n\n\n

This will shoot you over to the embedded GraphiQL IDE that the WPGraphQL plugin provides and auto-populate it with a query and fragment for the Location model’s data.

\n\n\n\n

Go ahead and click the ▶️ icon to fire off the query, and you’ll see that the data for the Location posts you had created comes back in the response. Magic! ✨

\n\n\n\n

\n\n\n\n

We’ll make use of some of these GraphQL fields in our Next.js app in just a bit. For now, let’s turn our attention to the other Provider model we need to create.

\n\n\n\n

Provider Model

\n\n\n\n

In the WordPress admin sidebar, head back to Content Modeler > Models and click the button to create a new model.

\n\n\n\n

We’ll fill out the fields as follows:

\n\n\n\n

Give the model a Singular Name of “Provider” and a Plural Name of “Providers”.
Stick with the auto-generated Model ID of “provider”.
Set the API Visibility to “Public” so we’ll be able to query for Provider data from our decoupled JS app.
Select a Model Icon.
Enter a Description for the model.

\n\n\n\n

\n\n\n\n

Then we’ll click the button to create the new model.

\n\n\n\n

In the WordPress admin sidebar, you’ll see that a menu item has been added for our new Provider custom post type.

\n\n\n\n

Provider Model Fields

\n\n\n\n

Hit the + button to add a new field.

\n\n\n\n

The first several fields we’ll add the same way we added fields to the Location model. Here are the settings to use:

\n\n\n\n

Name – Make this a single-line Text field with a Name of “Name” and an API Identifier of “name”.
Credentials – Make this a single-line Text field with a Name of “Credentials” and an API Identifier of “credentials”.
Bio – Make this a Rich Text field with a Name of “Bio” and an API Identifier of “bio”.
Practicing Since – Make this a Number field with a Name of “Practicing Since” and an API Identifier of “practicingSince”. For Number Type, select “Integer”.

\n\n\n\n

Next, we’ll see our first and only Relationship field. This kind of field is very useful for maintaining relationships between posts. In our app, we’re going to use it to keep track of which Providers practice at which Locations.

\n\n\n\n

Click the + button to add one more field. Configure it like this:

\n\n\n\n

Select a field type of Relationship.
Enter a Name of “Locations”.
Stick with the auto-generated API Identifier of “locations”.
For Model to Reference, select “Locations”. This tells ACM which model to use at the other end of this relationship.
For Connections, select “Many to Many”, since many of our healthcare Providers will practice at many different Locations.
Enter a Description of “Locations where the provider practices” to help us remember what this relationship represents.

\n\n\n\n

Click the button to create this field.

\n\n\n\n

Specialty Taxonomy

\n\n\n\n

We’re done creating our fields for the Provider model, but we still need a way to group together Providers based on their specialty (Emergency Medicine, Pediatrics, etc.). That’s a perfect use-case for a WordPress taxonomy.

\n\n\n\n

From the WordPress admin sidebar, go to Content Modeler > Taxonomies.

\n\n\n\n

In the Add New section, configure a new taxonomy thusly:

\n\n\n\n

Enter a Singular Name of “Specialty”.
Enter a Plural Name of “Specialties”.
Stick with the auto-generated Taxonomy ID of “specialty”.
For Models, select “Providers”.
Set API Visibility to “Public” to make sure this taxonomy is added to the GraphQL schema.

\n\n\n\n

\n\n\n\n

Click the button to create the taxonomy.

\n\n\n\n

As a final step in this section, head to Providers > Add New in the WordPress admin sidebar. Then create a few dummy Provider posts so we have some data to work with.

\n\n\n\n

Provider Model Query

\n\n\n\n

Our Provider model has been created, including its locations Relationship field and the Specialty taxonomy. Just as we did for the Location model, let’s fire off a test query to take it for a spin.

\n\n\n\n

Head back to the Content Modeler > Models page.

\n\n\n\n

Click the ... icon next to our Provider model, then click “Open in GraphiQL”.

\n\n\n\n

This will once again shoot you over to the embedded GraphiQL IDE that the WPGraphQL plugin provides. This time, it will be auto-populated with a query and fragment for the Provider model’s data.

\n\n\n\n

If it’s not there already, add in fields to get the Specialty taxonomy term names for each Provider, like this:

\n\n\n\n

specialties {\n  nodes {\n    name\n  }\n}

\n\n\n\n

Go ahead and click the ▶️ icon to fire off the query, and you’ll see that the data for the Provider posts you had created comes back in the response.

\n\n\n\n

Done! Our Location and Provider content models are now fully built out, and we’ve seen how we can query for each via WPGraphQL. Now let’s query for this data from our frontend Next.js app.

\n\n\n\n

Next.js App Walkthrough

\n\n\n\n

You can follow these steps to get up and running with the Next.js app on your machine:

\n\n\n\n

Clone down the Next.js app repo.
Create a .env.local file inside of the app’s root folder. Open that file in a text editor and paste in NEXT_PUBLIC_WORDPRESS_API_URL=http://acm-demo.local/graphql, replacing http://acm-demo.local with the domain for your local WordPress site. This is the endpoint that Apollo Client will use when it sends requests to your WordPress backend.
Run npm install (or yarn) to install the app’s NPM dependencies.
Run npm run dev to get the server running locally.
You should now be able to visit http://localhost:3000/ in a web browser and see the app’s homepage.

\n\n\n\n

Providers Page

\n\n\n\n

Let’s first take a look at the Providers page. Navigate to /providers. You should see a list of Provider cards. Let’s open up pages/providers.js in a code editor to see how it works.

\n\n\n\n

export default function Providers({ providers }) {\n  return (\n    <Layout>\n      <h1>Providers</h1>\n      <ProvidersList providers={providers} />\n    </Layout>\n  );\n}\n\nexport async function getStaticProps() {\n  const response = await client.query({\n    query: GET_PROVIDERS,\n  });\n\n  return {\n    props: {\n      providers: response?.data?.providers?.nodes ?? [],\n    },\n  };\n}

\n\n\n\n

You can see that inside of Next.js’ getStaticProps() function, we’re using Apollo Client to query for the list of providers. That data is then passed into the Providers component as a prop.

\n\n\n\n

The GraphQL query that we’re firing off to get this data looks like this:

\n\n\n\n

const GET_PROVIDERS = gql`\n  query getProviders {\n    providers(first: 10) {\n      nodes {\n        ...ProviderCardFields\n      }\n    }\n  }\n  ${PROVIDER_CARD_FIELDS}\n`;

\n\n\n\n

…and the ProviderCardFields fragment that it uses is being pulled in from components/ProviderCard.js. It looks like this:

\n\n\n\n

export const PROVIDER_CARD_FIELDS = gql`\n  fragment ProviderCardFields on Provider {\n    databaseId\n    uri\n    name\n    credentials\n    profilePhoto {\n      sourceUrl\n      altText\n    }\n    specialties {\n      nodes {\n        name\n      }\n    }\n    locations {\n      nodes {\n        databaseId\n        name\n        uri\n      }\n    }\n  }\n`;

\n\n\n\n

You can see that these fields look very similar to the ones we used in the test query we fired off in the GraphiQL IDE.

\n\n\n\n

These fields are broken out into a fragment for code colocation; from the components/ProviderCard.js file, you can easily manage both the GraphQL fields being requested and how they’re used inside of the component in that same file.

\n\n\n\n

Back in our pages/providers.js file, you can see that we’re taking the list of providers and rendering a ProvidersList component.

\n\n\n\n

The ProvidersList component lives in components/ProvidersList.js and looks like this:

\n\n\n\n

export default function ProvidersList({ providers }) {\n  return (\n    <ul className=\"doctors-list\">\n      {providers.map((provider) => (\n        <li key={provider.databaseId}>\n          <ProviderCard provider={provider} />\n        </li>\n      ))}\n    </ul>\n  );\n}

\n\n\n\n

You can see that it renders a ul, then maps over the providers and renders an li for each with a ProviderCard component inside.

\n\n\n\n

The ProviderCard component lives in components/ProviderCard.js and looks like this:

\n\n\n\n

export default function ProviderCard({ provider }) {\n  const { uri, name, credentials, profilePhoto, specialties, locations } =\n    provider;\n\n  return (\n    <article className=\"card\">\n      <Link href={uri}>\n        <a>\n          <h2>\n            {name}, {credentials}\n          </h2>\n        </a>\n      </Link>\n      {profilePhoto ? (\n        <Link href={uri}>\n          <a>\n            <img src={profilePhoto.sourceUrl} alt={profilePhoto.altText} />\n          </a>\n        </Link>\n      ) : null}\n      <h3>Specialty</h3>\n      {specialties.nodes.map((specialty) => specialty.name).join(\", \")}\n      <h3>Locations</h3>\n      <ul className=\"locations-list\">\n        {locations.nodes.map((location) => {\n          return (\n            <li key={location.databaseId}>\n              🏥 <Link href={location.uri}>{location.name}</Link>\n            </li>\n          );\n        })}\n      </ul>\n    </article>\n  );\n}

\n\n\n\n

This component is responsible for rendering the individual cards that you see on the /providers page that list the details about each provider.

\n\n\n\n

There are a few noteworthy things here:

\n\n\n\n

The person’s name and profile photo (if they have one) are both links that point to that single Provider page.
We’re mapping over the Specialty taxonomy terms that this provider has and displaying them on a list. In your applications, you can even go a step further and create taxonomy archive pages using the WPGraphQL Tax Query extension.
We’re making use of our Provider => Locations relationships. We map over the locations and for each, render a link that points to that single Location page.

\n\n\n\n

Next, let’s explore the single Provider page (#1 on the list above).

\n\n\n\n

Click on a provider’s name or photo to be sent to their single Provider page. It’ll look something like this:

\n\n\n\n

Open up pages/provider/[id].js in a code editor to see the code for this page.

\n\n\n\n

Inside of getStaticProps(), we’re firing off the GET_PROVIDER query and passing through to it the provider’s id that’s in the URL. When that provider’s data comes back, it is passed through to the Provider component as a prop.

\n\n\n\n

const GET_PROVIDER = gql`\n  query getProvider($id: ID!) {\n    provider(id: $id, idType: DATABASE_ID) {\n      name\n      credentials\n      bio\n      practicingSince\n      profilePhoto {\n        sourceUrl\n        altText\n      }\n      specialties {\n        nodes {\n          name\n        }\n      }\n      locations {\n        nodes {\n          databaseId\n          name\n          uri\n        }\n      }\n    }\n  }\n`;\n\nexport async function getStaticProps(context) {\n  const { id } = context.params;\n  const response = await client.query({\n    query: GET_PROVIDER,\n    variables: { id },\n  });\n\n  const provider = response?.data?.provider;\n\n  if (!provider) {\n    return { notFound: true };\n  }\n\n  return {\n    props: { provider },\n    revalidate: 600,\n  };\n}

\n\n\n\n

The GET_PROVIDER query should give you a good sense of what it looks like to get the data for one of your ACM model’s individual posts.

\n\n\n\n

The Provider component that’s responsible for rendering the page looks like this:

\n\n\n\n

export default function Provider({ provider }) {\n  const {\n    name,\n    credentials,\n    bio,\n    practicingSince,\n    profilePhoto,\n    specialties,\n    locations,\n  } = provider;\n\n  return (\n    <Layout>\n      <Link href=\"/providers\">\n        <a className=\"providers-link\">&#8592; View Providers</a>\n      </Link>\n      <article className=\"provider\">\n        {profilePhoto ? (\n          <img src={profilePhoto.sourceUrl} alt={profilePhoto.altText} />\n        ) : null}\n        <h1>\n          {name}, {credentials}\n        </h1>\n        <p className=\"practicing-since\">Practicing since {practicingSince}</p>\n        <h2>Bio</h2>\n        <div dangerouslySetInnerHTML={{ __html: bio }} />\n        <h2>Specialty</h2>\n        {specialties.nodes.map((specialty) => specialty.name).join(\", \")}\n        <h2>Locations</h2>\n        <ul className=\"locations-list\">\n          {locations.nodes.map((location) => {\n            return (\n              <li key={location.databaseId}>\n                🏥 <Link href={location.uri}>{location.name}</Link>\n              </li>\n            );\n          })}\n        </ul>\n      </article>\n    </Layout>\n  );\n}

\n\n\n\n

Again, we see that we’re looping over the locations and rendering a link for each. Go ahead and click through to one of those single Location pages.

\n\n\n\n

The page you land on will look something like this:

\n\n\n\n

Now let’s open up pages/location/[id].js in a code editor to see how it works. You’ll notice a similar pattern to what we saw with the single Provider page.

\n\n\n\n

Inside of the getStaticProps() function, we fire off a GET_LOCATION query and pass to it the location’s id that’s in the URL. When that Provider‘s data comes back, it is passed through to the Location component as a prop.

\n\n\n\n

const GET_LOCATION = gql`\n  query getLocation($id: ID!) {\n    location(id: $id, idType: DATABASE_ID) {\n      name\n      description\n      photo {\n        sourceUrl\n        altText\n      }\n    }\n  }\n`;\n\nexport async function getStaticProps(context) {\n  const { id } = context.params;\n  const response = await client.query({\n    query: GET_LOCATION,\n    variables: { id },\n  });\n\n  const location = response?.data?.location;\n\n  if (!location) {\n    return { notFound: true };\n  }\n\n  return {\n    props: { location },\n    revalidate: 600,\n  };\n}

\n\n\n\n

Studying GET_LOCATION gives you yet another opportunity to see how we can query for one of your ACM model’s individual posts.

\n\n\n\n

Side-Note on Bi-Directional Relationship Queries

\n\n\n\n

On this page, it would also be cool to be able to query for all Providers who practice at this Location and provide links to each. That would involve querying the Provider => Location relationship in the opposite direction– starting with the Location and finding Providers related to it. At the time of this writing, ACM has not added the ability to do bi-directional relationship field queries like that, but the team is planning to add it in the near future.

\n\n\n\n

The Location component that’s responsible for rendering the page’s content looks like this:

\n\n\n\n

export default function Location({ location }) {\n  const { photo, name, description } = location;\n\n  return (\n    <Layout>\n      <Link href=\"/providers\">\n        <a className=\"providers-link\">&#8592; View Providers</a>\n      </Link>\n      <article className=\"location\">\n        {photo ? <img src={photo.sourceUrl} alt={photo.altText} /> : null}\n        <h1>{name}</h1>\n        <div dangerouslySetInnerHTML={{ __html: description }} />\n      </article>\n    </Layout>\n  );\n}

\n\n\n\n

Here, we render the Location‘s photo if it has one, the name of the location, and the description.

\n\n\n\n

That concludes the Next.js app walkthrough.

\n\n\n\n

Summary

\n\n\n\n

At this point, we’ve learned how to:

\n\n\n\n

Create ACM models
Create new posts for those models in the WordPress admin
Run test queries to get ACM model data using the GraphiQL IDE
Fire off GraphQL queries to fetch ACM model data from our decoupled Next.js app
Use the fetched ACM model data to render our React components

\n\n\n\n

I hope all of that is helpful to you as you dive into working with Atlas Content Modeler! The team working on it has put a lot of work into producing a single, unified tool for creating content models, with support for taxonomies and relationships being recent additions. They’re not done, however! A number of other field types will be added in the near future, along with other features. Stay tuned!

\n\n\n\n

How Can I Help?

\n\n\n\n

I’m glad you asked! We would love for you to try out ACM on your own projects. You can provide us with feedback on it in the following ways:

\n\n\n\n

Click ”Send Feedback” at the top of the Content Modeler page in your WordPress admin area to share your thoughts with us.
File bugs or feature requests in GitHub.

\n\n\n\n

Thanks for your interest in the project! 🙌

\n"},{"__typename":"Post","id":"cG9zdDoyODI=","uri":"/gutenberg-in-headless-wordpress-wpgraphql-gutenberg/","seo":{"__typename":"PostTypeSEO","readingTime":7,"title":"Gutenberg in Headless WordPress: WPGraphQL Gutenberg - WP Engine Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}}}},"title0":"Gutenberg in Headless WordPress: WPGraphQL Gutenberg","slug":"gutenberg-in-headless-wordpress-wpgraphql-gutenberg","content0":"\n

In the first post in this two-post series, we learned that WordPress does not currently provide a complete server-side registry of Gutenberg blocks, and that as a result, there are two primary, viable options for rendering blocks in headless WordPress projects:

\n\n\n\n

Render Gutenberg Blocks as HTML
Use WPGraphQL Gutenberg

\n\n\n\n

The first post discussed #1, and this post will cover approach #2.

\n\n\n\n

Before diving in, be sure to review the pros and cons of this approach listed in the excellent Gutenberg and Decoupled Applications post on the WPGraphQL blog to determine if it’s right for your project.

\n\n\n\n

How WPGraphQL Gutenberg Works

\n\n\n\n

As stated above, WordPress core doesn’t currently provide a complete server-registry of blocks. As a result, is not possible to query WordPress to get a list of all possible blocks and their data, and add that to the REST API / WPGraphQL schema. For headless sites, this means that you can’t fire off a REST API or WPGraphQL query to get all the blocks for a given post and have all the data you need.

\n\n\n\n

That’s where the WPGraphQL Gutenberg plugin comes in. It is an extension for WPGraphQL that works like this:

\n\n\n\n

When the Gutenberg block editor JavaScript application boots up, WPGraphQL Gutenberg gets the blocks registry and sends it in a network request to the WordPress PHP application.
When the request is received, the blocks registry is saved to the database.
Using the saved registry data, WPGraphQL Gutenberg adds the blocks to the WPGraphQL schema. This way, frontend applications are able to query for blocks and get all of their data.

\n\n\n\n

To gain a more in-depth understanding of how it works, check out the project’s documentation.

\n\n\n\n

Next we’ll learn how to work with WPGraphQL Gutenberg using this Next.js app as an example:

\n\n\n\n

https://github.com/kellenmace/wpgraphql-gutenberg-demo

\n\n\n\n

Setup

\n\n\n\n

To benefit from this post, you should be familiar with the basics of local WordPress development, WPGraphQL, React, and Apollo Client.

\n\n\n\n

Here are the steps for getting set up:

\n\n\n\n

WordPress Backend Setup

\n\n\n\n

Spin up local WordPress site.
Install and activate both the WPGraphQL and WPGraphQL Gutenberg plugins.
Create a couple blog posts using Gutenberg blocks to use for testing.
Click WPGraphQL Gutenberg Admin in the WordPress admin sidebar to be sent to the WPGraphQL Gutenberg options page, then click the Update button to update the blocks registry. This will loop through your posts, open the Gutenberg block editor inside of a hidden iframe for each, and save the blocks registry data to the database.

\n\n\n\n

Next.js App Setup

\n\n\n\n

Clone down the Next.js app repo.
Create a .env.local file inside of the app’s root folder. Open that file in a text editor and paste in NEXT_PUBLIC_WORDPRESS_API_URL=https://gutenbergdemo.local/graphql, replacing gutenbergdemo.local with the domain for your local WordPress site. This is the endpoint that Apollo Client will use when it sends requests to your WordPress backend.
Run npm install (or yarn) to install the app’s NPM dependencies.
Run npm run dev to get the server running locally.
You should now be able to visit http://localhost:3000/blog in a web browser and see the app’s Blog page.

\n\n\n\n

Render Blocks

\n\n\n\n

Open pages/[...uri].js in a code editor. Our single blog post pages will be rendered using this file.

\n\n\n\n

const GET_POST = gql`\n  query getPost($uri: ID!) {\n    post(id: $uri, idType: URI) {\n      title\n      ...BlocksField\n    }\n  }\n  ${BLOCKS_FIELD}\n`;\n\nexport async function getStaticProps(context) {\n  const uri = context.params.uri.join(\"/\");\n  const response = await client.query({\n    query: GET_POST,\n    variables: { uri },\n  });\n\n  const post = response?.data?.post;\n\n  if (!post) {\n    return { notFound: true };\n  }\n\n  return {\n    props: { post },\n    revalidate: 120,\n  };\n}

\n\n\n\n

You can see that inside of the getStaticProps() function, we run the GET_POST query and pass to it the URI for the current page as a variable. Once the result comes back, we extract the post data and return it to send it through as a prop to the SinglePost component in this same file.

\n\n\n\n

SinglePost looks like this:

\n\n\n\n

export default function SinglePost({ post }) {\n  const { title, blocks } = post;\n\n  return (\n    <Layout>\n      <article className=\"blog-post\">\n        <h1>{title}</h1>\n        <div>\n          {blocks\n            ? blocks.map((block, index) => <Block block={block} key={index} />)\n            : null}\n        </div>\n      </article>\n    </Layout>\n  );\n}

\n\n\n\n

You can see that if we have blocks data to render, we map over the blocks and render a Block component for each one.

\n\n\n\n

Now open /components/Block.js so we can take review the Block component. It looks something like this:

\n\n\n\n

export default function Block({ block }) {\n  const { attributes, name, innerBlocks } = block;\n\n  switch (name) {\n    case \"core/heading\":\n      return <HeadingBlock {...attributes} />;\n    case \"core/paragraph\":\n      return <ParagraphBlock {...attributes} />;\n    // TODO: Account for all other block types here.\n    default:\n      return null;\n  }\n}

\n\n\n\n

This component is little more that a switch() statement. It takes in the block prop, determines which block should be rendered based on its name, then renders the corresponding block component.

\n\n\n\n

In your project, you would need to account for all possible types of blocks at this point. Be sure to accommodate nested blocks (such as Column blocks) that need the innerBlocks data passed to them as a prop, in addition to attributes. Check out WebDevStudios’ Next.js WordPress Starter to see an example of how to do this.

\n\n\n\n

If you have a 1:1 mapping of blocks to components without the need to wrap any of them in divs/pass additional props/etc., you could even use this alternative approach which uses a JS object to map each block with its corresponding component.

\n\n\n\n

At the top of the Block.js file is this GraphQL fragment, which represents the data to be queried for all blocks:

\n\n\n\n

export const BLOCKS_FIELD = gql`\n  fragment BlocksField on Post {\n    blocks {\n      name\n      ... on CoreHeadingBlock {\n        attributes {\n          ... on CoreHeadingBlockAttributes {\n            ...HeadingBlockAttributes\n          }\n        }\n      }\n      ... on CoreParagraphBlock {\n        attributes {\n          ... on CoreParagraphBlockAttributes {\n            ...ParagraphBlockAttributes\n          }\n        }\n      }\n    }\n  }\n  ${HEADING_BLOCK_ATTRIBUTES}\n  ${PARAGRAPH_BLOCK_ATTRIBUTES}\n`;

\n\n\n\n

Notice that the fragments for individual block types are also interpolated into this template literal. This fragment is used in the [...url].js file we saw earlier with the ...BlocksField syntax.

\n\n\n\n

Now let’s take a look at an individual block component. Open up components/blocks/ParagraphBlock.js.

\n\n\n\n

export const PARAGRAPH_BLOCK_ATTRIBUTES = gql`\n  fragment ParagraphBlockAttributes on CoreParagraphBlockAttributes {\n    align\n    anchor\n    backgroundColor\n    className\n    content\n    dropCap\n    style\n    textColor\n  }\n`;\n\nfunction getClassName(align) {\n  if (align === \"center\" || align === \"right\") {\n    return `text-${align}`;\n  }\n\n  return \"text-left\";\n}\n\nexport default function ParagraphBlock({\n  align,\n  anchor,\n  backgroundColor,\n  className,\n  content,\n  dropCap,\n  style,\n  textColor,\n}) {\n  return <p className={getClassName(align)}>{parseHtml(content)}</p>;\n}

\n\n\n\n

At the top of this file is a GraphQL fragment in which we specify all the attributes we want included in our queries for Paragraph blocks.

\n\n\n\n

Now take a look at the ParagraphBlock component. You can see that we’re able to restructure the props passed in to pull out all of those same attributes.

\n\n\n\n

Having the fragment and the destructuring assignment colocated in the same file like this makes it easy to keep the two in sync; you can see all the data being requested, and all the data being received all in one shot.

\n\n\n\n

Disregard the parseHtml() function the content is passed through for the time being; we’ll discuss that in the next section.

\n\n\n\n

To see examples of many individual block components beyond the ones in this app’s repo, check out these from WebDevStudios’ Next.js WordPress Starter.

\n\n\n\n

Fix Internal Links

\n\n\n\n

Custom Server-side Block Parser

\n\n\n\n

Using this method, you’ll notice that internal links inside of Gutenberg blocks still point to the domain where your WordPress backend lives. You can fix that by using this Headless Block Parser plugin. Follow the steps in the readme to make use of it in your project.

\n\n\n\n

With that plugin in place, an internal link pointing to https://my-wp-backend.local/blog/hello-world in the post content will be rewritten to http://localhost:3000/blog/hello-world, for example. So make sure that your frontend app’s routing is set up property to accommodate that.

\n\n\n\n

An alternative approach you could take here would be to remove the domain, turning the links into relative URLs, such as /blog/hello-world. If you go that route, just be careful to account for all possible URL permutations– those that contain anchor links or query string parameters, those that point to the homepage (/), and so on.

\n\n\n\n

Convert Anchor tags to Link Components

\n\n\n\n

Above, I showed how to filter the blocks content to replace the domain of internal links with the domain of your decoupled JavaScript app. For single-page app (SPA) frameworks however, that isn’t quite enough. Although the internal links now point to the correct URL, they’re still just plain ol’ anchor tags (<a>). That means that when the user clicks one, a full page reload will be triggered rather than a route change using the SPA framework’s router. Let’s see how we can fix that and turn them into Link components instead using a JavaScript-based HTML parser.

\n\n\n\n

If you open up the package.json file, you’ll see that the html-react-parser library has been installed.

\n\n\n\n

Head over to /lib/parser.js now to see how it’s used.

\n\n\n\n

import parse, { domToReact } from \"html-react-parser\";\nimport Link from \"next/link\";\n\nexport default function parseHtml(html) {\n  const options = {\n    replace: ({ name, attribs, children }) => {\n      // Convert internal links to Next.js Link components.\n      const isInternalLink =\n        name === \"a\" && attribs[\"data-internal-link\"] === \"true\";\n\n      if (isInternalLink) {\n        return (\n          <Link href={attribs.href}>\n            <a {...attribs}>{domToReact(children, options)}</a>\n          </Link>\n        );\n      }\n    },\n  };\n\n  return parse(html, options);\n}

\n\n\n\n

The parse() function that html-react-parser provides parses the string of HTML into nodes. By passing in the options object with a replace() callback function inside, we tell the parser that when it encounters an anchor tag with a data-internal-link data attribute of true (an internal link), replace it with a Next.js Link component.

\n\n\n\n

Now we can then make use of this new parseHtml() function we created in our individual block components, like this:

\n\n\n\n

import parseHtml from \"../../lib/parser\";\n\nexport default function ParagraphBlock({\n  align,\n  anchor,\n  backgroundColor,\n  className,\n  content,\n  dropCap,\n  style,\n  textColor,\n}) {\n  return <p className={getClassName(align)}>{parseHtml(content)}</p>;\n}

\n\n\n\n

As a result of this work, our site visitors will be able to click on an internal link inside of a block’s content and experience an instantaneous route change via Next.js’ router, with no more full page reload.

\n\n\n\n

Other Uses

\n\n\n\n

The example above that shows converting internal anchor tag links to Link components is one use-case. You could use a parsing library to render components for other nodes inside of your blocks’ content as well though, if needed.

\n\n\n\n

Style Blocks

\n\n\n\n

In the first “Render Blocks as HTML” post in this series, we saw how it’s possible to import several stylesheets from WordPress core that provide base styles for the blocks HTML.

\n\n\n\n

Since this approach focuses on using WPGraphQL Gutenberg to query for JSON data and render all the block markup/JSX ourselves, however, you would also need to write custom styles that target each type of block.

\n\n\n\n

Trade-off: Control vs. Ease of Implementation

\n\n\n\n

As you can likely see, this approach gives developers a ton of control. You can query to get JSON data for your blocks all the way down to their individual attributes, then render and style them however you want. Implementing this approach requires a significant amount of work, however, so be prepared for that.

\n\n\n\n

In the first “Render Blocks as HTML” post in this series, I described how it’s possible to use an HTML parsing library to replace a few HTML nodes with components, such as the Link component that your JS framework provides. Working with WPGraphQL Gutenberg is quite the opposite experience; you must render components for every type of block yourself. If you need that level of control for your project, the additional effort could be worth it, though.

\n\n\n\n

As I mentioned at the top of this post, be sure to also review the pros and cons of this approach listed in the excellent Gutenberg and Decoupled Applications post on the WPGraphQL blog to determine if it’s right for your project.

\n\n\n\n

Wrapping Up

\n\n\n\n

I hope this post gave you a good sense of what querying for and rendering Gutenberg blocks using WPGraphQL Gutenberg looks like in practice. I also hope it’s a helpful piece to reference reference if you choose to implement this approach in your own headless WordPress projects.

\n\n\n\n

Do you have any questions about this method of rendering Gutenberg blocks content? Please reach out to let us know!

\n"},{"__typename":"Post","id":"cG9zdDoyODE=","seo":{"__typename":"PostTypeSEO","readingTime":9,"title":"Gutenberg in Headless WordPress: Render Blocks as HTML - WP Engine Developers"},"title0":"Gutenberg in Headless WordPress: Render Blocks as HTML","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}}}},"content0":"\n

The Gutenberg block editor is one of the key features driving WordPress forward. It provides a rich content authoring and editing experience, especially Gutenberg in a Headless WordPress site.

\n\n\n\n

Rendering Gutenberg content in a headless WordPress site isn’t without its share of challenges, however. Jason Bahl’s excellent Gutenberg and Decoupled Applications blog post gives an exhaustive overview of those challenges.

\n\n\n\n

As Jason explains, there is currently no complete server-side registry of blocks. The block.json file for each core block provides some data, but not all. Gutenberg blocks are registered in JavaScript, which is not executed or understood by the WordPress server. As a result, is not possible to query WordPress to get a list of all possible blocks and their data, and add that to the REST API / WPGraphQL schema. For a headless site, this means that you can’t fire off a REST API or WPGraphQL query to get all the blocks for a given post.

\n\n\n\n

Generally speaking, developers want to be able to execute a query to get the Gutenberg blocks for a given post and get structured data back in JSON format. They can then loop over those blocks in their frontend application and render React/Vue/Svelte/other components. Without a complete server-side registry of blocks, however, we don’t currently have that luxury. So where does that leave us? What are our options?

\n\n\n\n

In this two-part blog post series, I outline what I consider to be the two primary, viable options for rendering Gutenberg blocks in headless WordPress sites:

\n\n\n\n

Render Gutenberg Blocks as HTML
Use WPGraphQL Gutenberg

\n\n\n\n

We’ll discuss option #1 in this post.

\n\n\n\n

Before diving in, be sure to review the pros and cons of this approach listed in the Gutenberg and Decoupled Applications post to determine if it’s right for your project.

\n\n\n\n

An example Next.js app that uses the method described below to render Gutenberg blocks content is available here:

\n\n\n\n

https://github.com/kellenmace/gutenberg-demo-blocks-as-html

\n\n\n\n

Render Gutenberg Blocks as HTML

\n\n\n\n

When core Gutenberg blocks are saved to the database, the post content looks something like this:

\n\n\n\n

<!-- wp:paragraph {\"dropCap\":true,\"style\":{\"elements\":{\"link\":{\"color\":{\"text\":\"var:preset|color|orange\"}}},\"typography\":{\"lineHeight\":\"1.8\"}},\"backgroundColor\":\"gray\",\"textColor\":\"blue\",\"fontSize\":\"small\"} -->\n\n<p class=\"has-drop-cap has-blue-color has-gray-background-color has-text-color has-background has-link-color has-small-font-size\" style=\"line-height:1.8\">Here is some text.</p>\n\n<!-- /wp:paragraph -->\n\n\n<!-- wp:image {\"id\":12,\"width\":225,\"height\":150,\"sizeSlug\":\"medium\",\"linkDestination\":\"none\",\"className\":\"is-style-rounded path-in-woods\"} -->\n\n<figure class=\"wp-block-image size-medium is-resized is-style-rounded path-in-woods\" id=\"path-in-woods\"><img src=\"http://gutenbergdemo.local/wp-content/uploads/2021/08/e1d8a0cd-c00c-3b96-b50e-18f5bd502fb0-300x200.jpg\" alt=\"Photo of a path through the woods\" class=\"wp-image-12\" width=\"225\" height=\"150\" title=\"Here is a title\"/></figure>\n\n<!-- /wp:image -->

\n\n\n\n

You can see here that we have two blocks: Paragraph and Image. The markup is there for each, as well as additional JSON data about the block stored inside of HTML comments.

\n\n\n\n

When you request a post’s content via the REST API or WPGraphQL, WordPress gets that data from the database and runs it through a few filters that parse the blocks and generate the fully rendered HTML that looks like this:

\n\n\n\n

<p class=\"wp-elements-612777c487d3f has-drop-cap has-blue-color has-gray-background-color has-text-color\n  has-background has-link-color has-small-font-size\" style=\"line-height:1.8\">Here is some text.</p>\n<style>\n  .wp-elements-612777c487d3f a {\n    color: var(--wp--preset--color--orange) !important;\n  }\n</style>\n\n<figure class=\"wp-block-image size-medium is-resized is-style-rounded path-in-woods\"\n  id=\"path-in-woods\"><img loading=\"lazy\"\n    src=\"http://gutenbergdemo.local/wp-content/uploads/2021/08/e1d8a0cd-c00c-3b96-b50e-18f5bd502fb0-300x200.jpg\"\n    alt=\"Photo of a path through the woods\" class=\"wp-image-12\" width=\"225\" height=\"150\" title=\"Here is a\n    title\"\n    srcset=\"http://gutenbergdemo.local/wp-content/uploads/2021/08/e1d8a0cd-c00c-3b96-b50e-18f5bd502fb0-300x200.jpg\n    300w, http://gutenbergdemo.local/wp-content/uploads/2021/08/e1d8a0cd-c00c-3b96-b50e-18f5bd502fb0-1024x682.jpg 1024w,\n    http://gutenbergdemo.local/wp-content/uploads/2021/08/e1d8a0cd-c00c-3b96-b50e-18f5bd502fb0-768x512.jpg 768w,\n    http://gutenbergdemo.local/wp-content/uploads/2021/08/e1d8a0cd-c00c-3b96-b50e-18f5bd502fb0.jpg 1357w\"\n    sizes=\"(max-width: 225px) 100vw, 225px\" />\n</figure>

\n\n\n\n

So the most straightforward approach is just to render this HTML to the page in your decoupled frontend application. In a React app for example, you can do so using dangerouslySetInnerHTML, like this:

\n\n\n\n

export default function SinglePost({ post }) {\n  const { title, content } = post;\n\n  return (\n    <article className=\"blog-post\">\n      <h1>{title}</h1>\n      <div dangerouslySetInnerHTML={{ __html: content }} />\n    </article>\n  );\n}

\n\n\n\n

Fix Internal Links for Headless Gutenberg

\n\n\n\n

Using this method, you’ll notice that internal links still point to the domain where your WordPress backend lives. You can fix that with a PHP filter function like this:

\n\n\n\n

 /**\n  * Modify internal link URLs to point to the decoupled frontend app.\n  *\n  * @param string $content Post content.\n  *\n  * @return string Post content, with internal link URLs replaced.\n  */\nfunction replace_headless_content_link_urls(string $content): string\n{\n    if (!is_graphql_request() && !defined('REST_REQUEST')) {\n        return $content;\n    }\n\n    // TODO: Get this value from an environment variable or the database.\n    $frontend_app_url = 'http://localhost:3000';\n    $site_url         = site_url();\n\n    return str_replace('href=\"' . $site_url, 'href=\"' . $frontend_app_url, $content);\n}\nadd_filter('the_content', 'replace_headless_content_link_urls');

\n\n\n\n

A WordPress plugin that contains this code is available here.

\n\n\n\n

The if (!is_graphql_request() && !defined('REST_REQUEST')) guard clause ensures that this URL replacement code only runs during WPGraphQL or REST API requests. This way, if you have any traditional, server-rendered pages, their post content will be unaffected.

\n\n\n\n

You can see that $frontend_app_url = 'https://localhost:3000'; is hardcoded here. Update that line so that the frontend app URL is pulled either from an environment variable or from a value in the database. Then you’ll be able to have it set to a different URL depending on the environment (development/staging/production).

\n\n\n\n

With this function in place, an internal link pointing to https://my-wp-backend.local/blog/hello-world in the post content will be rewritten to http://localhost:3000/blog/hello-world, for example. So make sure that your frontend app’s routing is set up properly to accommodate that.

\n\n\n\n

An alternative approach you could take here would be to remove the domain, turning the links into relative URLs, such as /blog/hello-world. If you go that route, be careful to account for all possible URL permutations– those that contain anchor links or query string parameters, those that point to the homepage (/), and so on.

\n\n\n\n

Style Blocks

\n\n\n\n

Just like on traditional, monolithic WordPress sites, you need to write styles for every type of block. This way, regardless of which blocks are present for a given post, you have your bases covered.

\n\n\n\n

WordPress has an NPM package that includes the base styles it uses to style core blocks. You can install it with npm install @wordpress/block-library, then import the stylesheets into your decoupled frontend app like this:

\n\n\n\n

import \"@wordpress/block-library/build-style/common.css\"\nimport \"@wordpress/block-library/build-style/style.css\"\nimport \"@wordpress/block-library/build-style/theme.css\"

\n\n\n\n

Once those base styles have been applied to the blocks, you can customize the look and feel of the blocks further by writing custom styles. To see an example, you can reference the custom block styles that WordPress’ default “twentytwentyone” theme includes, here: https://github.com/WordPress/twentytwentyone/tree/trunk/assets/sass/05-blocks

\n\n\n\n

Use a Parser to Convert Some Blocks to Components

\n\n\n\n

Taking the HTML for many types of blocks (Paragraph, List, etc.) and rendering it directly to the page works great. For others, you may need to render an actual React/Vue/Svelte component instead for various reasons. Thankfully, a solution to that exists in the form of a parser.

\n\n\n\n

Example: Convert Anchor tags to Link Components

\n\n\n\n

In this section, we’ll see a good example of when and how to use a parser to replace anchor tags (<a>) with your JS framework’s Link component may be advantageous.

\n\n\n\n

In the “Fix Internal Links” section above, I showed how to filter the post content to replace the domain of internal links with the domain of your decoupled JavaScript app. For single-page app (SPA) frameworks, however, that isn’t quite enough. Although the internal links now point to the correct URL, they’re still just plain ol’ anchor tags (<a>). That means that when the user clicks one, a full-page reload will be triggered rather than a route change using the SPA framework’s router. Let’s see how we can fix that in a Next.js app and turn them into Link components instead.

\n\n\n\n

First, we’ll modify the PHP function we saw earlier like this:

\n\n\n\n

/**\n * Modify internal link URLs to point to the decoupled frontend app.\n *\n * @param string $content Post content.\n *\n * @return string Post content, with internal link URLs replaced.\n */\nfunction replace_headless_content_link_urls(string $content): string\n{\n    if (!is_graphql_request() && !defined('REST_REQUEST')) {\n        return $content;\n    }\n\n    // TODO: Get this value from an environment variable or the database.\n    $frontend_app_url = 'http://localhost:3000';\n    $site_url         = site_url();\n\n    return str_replace('href=\"' . $site_url, 'data-internal-link=\"true\" href=\"' . $frontend_app_url, $content);\n}\nadd_filter('the_content', 'replace_headless_content_link_urls');

\n\n\n\n

This is identical to the code snippet in the “Fix Internal Links” section above, except that we’re adding a data-internal-link data attribute to our internal links with this bit of code:

\n\n\n\n

data-internal-link=\"true\"

\n\n\n\n

This snippet makes it easy for us to identify internal links in our frontend JS app when the markup is parsed.

\n\n\n\n

You may be wondering why we can’t simply look for anchor tags that start with “http://localhost:3000″ to identify which are internal links. Remember though that the URL of the frontend app will change or be difficult to access depending on the environment (development/staging/production or server/client). So by using this data attribute approach, we can rest assured that we’ll be able to easily identify internal links across all environments.

\n\n\n\n

With that in place, we can implement the parser.

\n\n\n\n

First, we’ll run npm install html-react-parser to install the html-react-parser library we’ll use.

\n\n\n\n

In the Next.js app, we’ll create this /lib/parser.js file:

\n\n\n\n

import parse, { domToReact } from \"html-react-parser\";\nimport Link from \"next/link\";\n\nexport default function parseHtml(html) {\n  const options = {\n    replace: ({ name, attribs, children }) => {\n      // Convert internal links to Next.js Link components.\n      const isInternalLink =\n        name === \"a\" && attribs[\"data-internal-link\"] === \"true\";\n\n      if (isInternalLink) {\n        return (\n          <Link href={attribs.href}>\n            <a {...attribs}>{domToReact(children, options)}</a>\n          </Link>\n        );\n      }\n    },\n  };\n\n  return parse(html, options);\n}

\n\n\n\n

The parse() function that html-react-parser provides will parse the string of HTML into nodes. By passing in the options object with a replace() callback function inside, we tell the parser that when it encounters an anchor tag with a data-internal-link data attribute of true (an internal link), replace it with a Next.js Link component.

\n\n\n\n

Now we can then make use of this new parseHtml() function we created in our single blog post React component, like this:

\n\n\n\n

import parseHtml from \"../lib/parser\";\n\nexport default function SinglePost({ post }) {\n  const { title, content } = post;\n\n  return (\n    <article className=\"blog-post\">\n      <h1>{title}</h1>\n      <div>{parseHtml(content)}</div>\n    </article>\n  );\n}

\n\n\n\n

As a result of this work, our site visitors will be able to click on an internal link in a blog post. Visitors will experience an instantaneous route change via Next.js’ router, with no more full page reload.

\n\n\n\n

Other Uses

\n\n\n\n

The example above that shows converting internal anchor tag links to Link components is one use-case, but there are many more you may have.

\n\n\n\n

Trade-off: Control vs. Ease of Implementation

\n\n\n\n

I view this approach as the easiest to implement. Working with already-rendered HTML and swapping out some of the nodes with custom components using a parser saves a lot of development time. You don’t have to query for and write components and styles from scratch for each individual type of block. If this approach suits the needs of your project, I would seriously consider it.

\n\n\n\n

This ease of implementation comes at a cost, however: less control. If you need to be able to query for the individual attributes for every type of block, then render them using custom components and custom markup/JSX, consider the WPGraphQL Gutenberg approach discussed in post #2 of this series instead.

\n\n\n\n

Wrapping Up

\n\n\n\n

I hope this post gave you a good sense of what rendering Gutenberg blocks as HTML looks like in practice. I also hope it’s a helpful piece to reference if you choose this approach in your own Gutenberg headless WordPress projects.

\n\n\n\n

Do you have any questions about this method of rendering Gutenberg blocks content? Please reach out to let us know!

\n","slug":"gutenberg-in-headless-wordpress-render-blocks-as-html","uri":"/gutenberg-in-headless-wordpress-render-blocks-as-html/"},{"__typename":"Post","id":"cG9zdDoyNjU=","seo":{"__typename":"PostTypeSEO","readingTime":10,"title":"What is Atlas Content Modeler? - WP Engine Developers"},"title0":"What is Atlas Content Modeler?","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}}}},"content0":"\n

Atlas Content Modeler has the potential to become a BIG deal in the headless WordPress space. Up until this point, creating the content models for your headless WordPress site has required you to:

\n\n\n\n

Register your custom post types and taxonomies with Custom Post Type UI
Expose custom fields in the GraphQl schema with Advanced Custom Fields + WPGraphQL for Advanced Custom Fields
Create efficient many-t0-many relationships between posts or users using MB Relationships + WPGraphQL MB Relationships

\n\n\n\n

To complicate things further, many plugins designed before the headless WordPress era have aspects that make them less-than-ideal for use on headless sites. Some examples:

\n\n\n\n

Custom Post Type UI presents the user with several fields that don’t apply to headless architectures and unnecessarily clutter the interface.
Advanced Custom Fields allows users to select from several jQuery-powered fields, even though virtually all modern JavaScript frameworks do not use jQuery (React/Vue/Svelte/etc.).

\n\n\n\n

Some developers may prefer to swap out some of the plugins mentioned above for others or perhaps write custom code to register their custom post types and taxonomies. However, the central point remains: creating content models for headless WordPress sites is cumbersome and requires cobbling together several tools not designed with headless architectures in mind.

\n\n\n\n

Introducing Atlas Content Modeler

\n\n\n\n

Atlas Content Modeler (ACM) is an open-source project from WP Engine that strives to remove all of this complication and confusion and ultimately simplify the process of creating content models for your headless WordPress site. With a single tool, you’ll be able to create a new content model, define the custom fields and taxonomies for it, develop relationships between the model and other posts or users, and have all of that data automatically available to you via the WordPress REST API or WPGraphQL! 🤯

\n\n\n\n

Not all of those features are in place as of the time of this writing, however. Currently, you can register content models and assign several custom fields to them. The Atlas Content Modeler team plans on adding support for other custom field types, taxonomies, and relationships are on the project roadmap.

\n\n\n\n

Let’s dive in and get a feel for what working with ACM looks like in practice.

\n\n\n\n

Content Modeler Real-World Usage

\n\n\n\n

Let’s say that I’m a developer working on a headless WordPress site for a client of mine. The client runs a company that does construction and renovation work. In the discovery phase of the project, the client tells me that they want to manage the company’s projects in the WordPress admin and have the data for those projects displayed on the frontend of the site. Further discussion with the client reveals that we needed a “Project” content model that looks this:

\n\n\n\n

Project

\n\n\n\n

Street Address (single-line text field)
Contact Name (single-line text field)
Work Order Number (single-line text field)
Description of Work (rich text field)
Cost (number field)
Date of Service (date field)
Property Photo (media field)
Follow-up Inspection Required (boolean field)

\n\n\n\n

Local Setup

\n\n\n\n

Armed with that knowledge, I fire up a new local WordPress site and get to work. I install and activate the Atlas Content Modeler plugin. From the WordPress admin sidebar, I click on Content Modeler, then click the Add New button to create a new model.

\n\n\n\n

Project Model Creation

\n\n\n\n

I define the Single Name, Plural Name, Model ID, select the Model Icon and provide the Description. I’m also careful to set the API Visibility to Public since I want the data for this Project model to be added to the public GraphQL schema. That way, I’ll be able to query for Project data from my decoupled frontend app.

\n\n\n\n

The page now looks like this:

\n\n\n\n

\n\n\n\n

I click the button to create the model. At this point, the Project custom post type has been registered, and I see that a new Projects menu item has been added to the WordPress Admin sidebar.

\n\n\n\n

Next, we can define the custom fields that our model requires.

\n\n\n\n

Custom Fields

\n\n\n\n

I click on the + icon to add a new field. This field will be for them Street Address, so I’ll choose Text for the field type. I’ll give it the name “Street Address” and go with the auto-generated “streetAddress” API identifier. We’ll make use of this API identifier later when we run queries to get our data. The field’s settings now look like this:

\n\n\n\n

I click the button to create the field, then create the Contact Name and Work Order Number fields, both of which are also single-line text fields.

\n\n\n\n

For the Description of Work field, I choose Rich Text the field type and give it a name and API identifier.

\n\n\n\n

This process of adding fields is repeated for the Cost, Date of Service, Property Photo and Follow-up Inspection Required fields, registering them as Number, Date, Media and Boolean field types, respectively.

\n\n\n\n

With all fields added, I can see all of my registered fields on the list.

\n\n\n\n

\n\n\n\n

Working with the Model in the WordPress Admin

\n\n\n\n

Now that I’ve defined my content model, I want to see what the experience will be like for my client when they enter project data. I go to Projects > Add New in the WordPress, Admin sidebar to take a look. All the custom fields I defined are present, and they’re all displaying as the correct field types.

\n\n\n\n

Next, I can fill them in with project dummy data and save the Project post.

\n\n\n\n

\n\n\n\n

Query for Data via WPGraphQL

\n\n\n\n

Here’s where things get cool! 😎

\n\n\n\n

From the WordPress Admin sidebar, I head back over to Content Modeler. I click on the ellipsis (…) icon, then click on Open in GraphiQL.

\n\n\n\n

Before my very eyes, WPGraphQL’s GraphiQL IDE page opens up with a query and fragment already pre-populated with all the data for my model. I click the ▶ icon to execute the query and see that the first Project I had created is included in the response, along with all of the data for its custom fields! 💥

\n\n\n\n

This is powerful! Now, I’m ready to spin up a new frontend app using my favorite JavaScript framework (Next.js/Gatsby/Nuxt/SvelteKit/other). I can pull data from my headless WordPress backend, then fire off queries very similar to the one shown above.

\n\n\n\n

Next.js App Example

\n\n\n\n

Here’s an example of a Projects list page component in a Next.js app:

\n\n\n\n

// pages/projects.js\n\nimport { gql } from \"@apollo/client\";\nimport Link from \"next/link\";\n\nimport { client } from \"../lib/apolloClient\";\nimport Layout from \"../components/Layout\";\n\nconst GET_PROJECTS = gql`\n  query getProjects {\n    projects(first: 10, after: null) {\n      nodes {\n        databaseId\n        streetAddress\n        propertyPhoto {\n          mediaItemUrl\n          altText\n        }\n      }\n    }\n  }\n`;\n\nexport default function Projects(props) {\n  const { projects } = props;\n\n  return (\n    <Layout>\n      <h1>Projects</h1>\n      <ul className=\"projects-list\">\n        {projects.map((project) => (\n          <li key={project.databaseId}>\n            <article className=\"project-card\">\n              {project.propertyPhoto ? (\n                <Link href={`/project/${project.databaseId}`}>\n                  <a>\n                    <img\n                      src={project.propertyPhoto.mediaItemUrl}\n                      alt={project.propertyPhoto.altText}\n                      className=\"property-photo\"\n                    />\n                  </a>\n                </Link>\n              ) : null}\n              <h2>\n                <Link href={`/project/${project.databaseId}`}>\n                  <a>{project.streetAddress}</a>\n                </Link>\n              </h2>\n            </article>\n          </li>\n        ))}\n      </ul>\n    </Layout>\n  );\n}\n\nexport async function getStaticProps() {\n  const response = await client.query({\n    query: GET_PROJECTS,\n  });\n\n  return {\n    props: {\n      projects: response.data.projects.nodes,\n    },\n  };\n}

\n\n\n\n

As you can see in the example, I fire off a query to get Projects data, then map over the results displaying them in a list.

\n\n\n\n

This Projects list page looks like this on the frontend of the site:

\n\n\n\n

\n\n\n\n

Here’s an example of a single Project page component in the same app:

\n\n\n\n

// pages/project/[id].js\n\nimport { gql } from \"@apollo/client\";\nimport parse from \"html-react-parser\";\nimport Link from \"next/link\";\n\nimport { client } from \"../../lib/apolloClient\";\nimport Layout from \"../../components/Layout\";\n\nconst GET_PROJECT = gql`\n  query getProject($databaseId: ID!) {\n    project(id: $databaseId, idType: DATABASE_ID) {\n      streetAddress\n      contactName\n      workOrderNumber\n      descriptionOfWork\n      cost\n      dateOfService\n      propertyPhoto {\n        mediaItemUrl\n        altText\n      }\n    }\n  }\n`;\n\nfunction formatCurrency(number) {\n  const formatter = new Intl.NumberFormat(\"en-US\", {\n    style: \"currency\",\n    currency: \"USD\",\n  });\n\n  return formatter.format(number);\n}\n\nconst formatDate = (date) => new Date(date).toLocaleDateString();\n\nexport default function Project({ project }) {\n  const {\n    streetAddress,\n    contactName,\n    workOrderNumber,\n    descriptionOfWork,\n    cost,\n    dateOfService,\n    propertyPhoto,\n  } = project;\n\n  return (\n    <Layout>\n      <Link href=\"/projects\">\n        <a>&#8592; Back to projects</a>\n      </Link>\n      <article className=\"single-project\">\n        <h1>{streetAddress}</h1>\n        {propertyPhoto ? (\n          <img\n            src={propertyPhoto.mediaItemUrl}\n            alt={propertyPhoto.altText}\n            className=\"property-photo\"\n          />\n        ) : null}\n        <ul className=\"project-details\">\n          <li>\n            <span className=\"label\">👤 Contact</span>\n            <span className=\"value\">{contactName}</span>\n          </li>\n          <li>\n            <span className=\"label\">📁 Work Order #</span>\n            <span className=\"value\">{workOrderNumber}</span>\n          </li>\n          <li>\n            <span className=\"label\">💰 Cost</span>\n            <span className=\"value\">{formatCurrency(cost)}</span>\n          </li>\n          <li>\n            <span className=\"label\">📅 Date of Service</span>\n            <span className=\"value\">{formatDate(dateOfService)}</span>\n          </li>\n        </ul>\n        <div className=\"project-description\">{parse(descriptionOfWork)}</div>\n      </article>\n    </Layout>\n  );\n}\n\nexport function getStaticPaths() {\n  return {\n    paths: [],\n    fallback: \"blocking\",\n  };\n}\n\nexport async function getStaticProps(context) {\n  const response = await client.query({\n    query: GET_PROJECT,\n    variables: {\n      databaseId: context.params.id,\n    },\n  });\n\n  const project = response?.data?.project;\n\n  if (!project) {\n    return { notFound: true };\n  }\n\n  return {\n    props: { project },\n    revalidate: 60,\n  };\n}

\n\n\n\n

You can see that the GraphQL query being run here is for a single Project, which I’m identifying by its databaseId (a.k.a. it’s “post ID” in WordPress parlance). Using the data in the response, the address, photo, details, and description for the project are rendered.

\n\n\n\n

This single Project page looks like this on the frontend of the site:

\n\n\n\n

\n\n\n\n

The source code for this Next.js app is here, if you’d like to reference it: https://github.com/kellenmace/atlas-content-modeler-demo.

\n\n\n\n

Where to Go from Here?

\n\n\n\n

By this point, I hope you can see the potential the Atlas Content Modeler has!

\n\n\n\n

The goal is for developers to no longer have to cobble together multiple tools that weren’t designed with headless WordPress in mind and then worry about exposing their data in the REST API / GraphQL schema. Instead, they can use ACM to register their custom content types and automatically expose them via REST/GraphQL all in one shot.

\n\n\n\n

As mentioned at the beginning of this post, only some custom field types are currently supported, but the team plans to add other field types, taxonomies, relationship fields, and more soon. Stay tuned!

\n\n\n\n

How Can I Help?

\n\n\n\n

I’m glad you asked! We would love for you to be a beta tester and try out ACM on your own projects. You can provide us with feedback on it in the following ways:

\n\n\n\n

Click ”Send Feedback” at the top of the Content Modeler page in your WordPress admin area to share your thoughts with us.
File bugs or feature requests in GitHub.

\n\n\n\n

Thanks for your interest in the project! 🙌

\n","slug":"what-is-atlas-content-modeler","uri":"/what-is-atlas-content-modeler/"},{"__typename":"Post","id":"cG9zdDoyMjI=","seo":{"__typename":"PostTypeSEO","readingTime":19,"title":"Headless WordPress Authentication with Native Cookies - WP Engine Developers"},"title0":"Headless WordPress Authentication with Native Cookies","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}}}},"content0":"\n

When developing a traditional, monolithic WordPress site, you typically don’t give authentication a second thought. WordPress already provides a native cookie-based authentication system that works out of the box.

\n\n\n\n

What you may not know is that for a headless WordPress project, it’s possible to leverage that same authentication system in your decoupled JavaScript frontend app!

\n\n\n\n

In this post, we’ll explore a Next.js app that uses WordPress’ own native authentication cookies to provide the following functionality:

\n\n\n\n

Log in
Log out
New user sign-ups
Password resets
User profile page
A “Members” page with gated content that only authenticated users can access
A “Create Post” page where users with the publish_posts capability can create new posts, but other users can’t.
A useAuth() custom hook that provides the user’s loggedIn status and user details to the rest of the app via React context.
Helper components to limit certain content to only authenticated/unauthenticated users.

\n\n\n\n

(A Gatsby.js port of the codebase also exists, here)

\n\n\n\n

To accomplish this, we’ll leverage the WPGraphQL CORS plugin, which allows us to tell WordPress to not only accept cookies from the domain where WP is installed, but also from the decoupled frontend app’s domain. That way, the same cookies can be used to authenticate users on both domains.

\n\n\n\n

Getting Started

\n\n\n\n

To benefit from this post, you should be familiar with the basics of local WordPress development, WPGraphQL, React, and Apollo Client.

\n\n\n\n

Here are the steps for getting set up:

\n\n\n\n

WordPress Backend Setup

\n\n\n\n

Set up a local WordPress site and get it running.
Install and activate the WPGraphQL, WPGraphQL CORS, and Headless WordPress Email Settings WordPress plugins.
From the WordPress admin sidebar, go to GraphQL > Settings and click the CORS Settings tab.
Check the checkboxes next to these options:
– Send site credentials
– Enable login mutation
– Enable logout mutation
In the Extend \"Access-Control-Allow-Origin” header field, enter http://localhost:3000 and click the button to save your changes.

\n\n\n\n

The CORS Settings page should now look like this:

\n\n\n\n

\n\n\n\n

Next.js App Setup

\n\n\n\n

Clone down the Next.js app repo.
Create a .env.local file inside of the app’s root folder. Open that file in a text editor and paste in NEXT_PUBLIC_WORDPRESS_API_URL=https://headlesswpcookieauth.local/graphql, replacing headlesswpcookieauth.local with the domain for your local WordPress site. This is the endpoint that Apollo Client will use when it sends requests to your WordPress backend.
Run npm install (or yarn) to install the app’s NPM dependencies.
Run npm run dev to get the server running locally.
You should now be able to visit http://localhost:3000/ in a web browser and see the app’s homepage.

\n\n\n\n

Alternatively, you can follow the steps for getting set up with the Gatsby.js port of this codebase.

\n\n\n\n

Try it Out!

\n\n\n\n

Take a minute to explore the app. Try logging in and logging out. You’ll notice that the top navigation bar re-renders to show different things when you’re logged in vs. logged out, and that some pages are only accessible when you’re logged in/out.

\n\n\n\n

How it Works

\n\n\n\n

At a high level, our authentication system works like this:

\n\n\n\n

An unauthenticated user navigates to the Log In page and attempts to log in.
Our app fires off a GraphQL request to the WordPress backend with that user’s email address and password.
If the credentials are valid, WordPress sends an HttpOnly cookie back to the client, along with a success response.
Knowing that the user has been logged in successfully, our app is then able to fire off a request to get some basic info about that user and re-render the app to display links and pages meant for authenticated users.
Requests made to the WordPress backend after that point include the auth cookie in the request headers, which is used to authenticate the user.

\n\n\n\n

A Note on Security

\n\n\n\n

That “HttpOnly” cookie part is important. Some other authentication strategies involve storing an authentication token in local storage or in a cookie that does not have the HttpOnly attribute. That means that the site would be vulnerable to a cross-site scripting (XSS) attack where some rogue client-side JavaScript code would be able to “reach” into local storage/the non-HttpOnly cookie to get the auth token, then make authenticated requests on behalf of the user without their permission. More info on that type of vulnerability can be found here.

\n\n\n\n

Since our cookie does have the HttpOnly attribute, it is not accessible at all via client-side JavaScript, and therefore not vulnerable to the type of cross-site scripting (XSS) attack mentioned above. This results in more robust security.

\n\n\n\n

Apollo Client Configuration

\n\n\n\n

Apollo Client is initialized in lib/apolloClient.ts.

\n\n\n\n

import { ApolloClient, InMemoryCache, createHttpLink } from \"@apollo/client\";\n\nconst link = createHttpLink({\n  uri: process.env.NEXT_PUBLIC_WORDPRESS_API_URL,\n  credentials: 'include',\n});\n\nexport const client = new ApolloClient({\n  cache: new InMemoryCache(),\n  link\n});

\n\n\n\n

The credentials: 'include', option is what tells Apollo to send the auth cookie along with every request.

\n\n\n\n

The client from that file is then passed as a prop into the ApolloProvider component in pages/_app.tsx, which allows us to make GraphQL network requests from anywhere in our app.

\n\n\n\n

`useAuth()` Hook

\n\n\n\n

Take a look at hooks/useAuth.tsx.

\n\n\n\n

const AuthContext = createContext(DEFAULT_STATE);\n\nexport const GET_USER = gql`\n  query getUser {\n    viewer {\n      id\n      databaseId\n      firstName\n      lastName\n      email\n      capabilities\n    }\n  }\n`;\n\nexport function AuthProvider({ children }: { children: ReactNode }) {\n  const { data, loading, error } = useQuery(GET_USER);\n  const user = data?.viewer;\n  const loggedIn = Boolean(user);\n\n  const value = {\n    loggedIn,\n    user,\n    loading,\n    error,\n  };\n\n  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>\n}\n\nconst useAuth = () => useContext(AuthContext);\n\nexport default useAuth;

\n\n\n\n

When our app first boots up, the GET_USER query defined here is fired off to see if the user is authenticated. If they are, loggedIn is toggled to true. It, along with the user data and loading and error states are passed down to the rest of our app via React context. This way, any component or hook in our app can use the useAuth() hook to access that authentication-related data.

\n\n\n\n

AuthContent & UnAuthContent Components

\n\n\n\n

These two components are used to conditionally render parts of our application that should only be shown to authenticated or unauthenticated users. They also redirect users who don’t meet that criterion to the proper page.

\n\n\n\n

AuthContent

\n\n\n\n

Open up components/AuthContent.tsx to see how this component works.

\n\n\n\n

export default function AuthContent({ children }: { children: ReactNode }) {\n  const { loggedIn, loading } = useAuth();\n  const router = useRouter();\n\n  // Navigate unauthenticated users to Log In page.\n  useEffect(() => {\n    if (!loading && !loggedIn) {\n      router.push('/log-in');\n    }\n  }, [loggedIn, loading, router]);\n\n  if (loggedIn) {\n    return <>{children}</>;\n  }\n\n  return <p>Loading...</p>;\n}

\n\n\n\n

The logic works like this:

\n\n\n\n

If the app just booted up and we don’t know whether or not the user is logged in yet, display a “Loading…” message.
If we have determined the user is logged in, display the children nested inside of this component and allow the user to stay on this page.
If we have determined the user is NOT logged in, redirect the user to the Log In page. The children nested inside of this component are never rendered.

\n\n\n\n

To see that in action, you can head over to the /profile page. The component for that page (pages/profile.tsx) does this:

\n\n\n\n

<AuthContent>\n  <ProfileForm />\n</AuthContent>

\n\n\n\n

If you try to navigate directly to that page as a logged-in user, you’ll see a loading message momentarily, followed by the user profile form.

\n\n\n\n

If you try to navigate there directly as a logged-out user though, you’ll see the loading message momentarily, then you will be redirected to the Log In page to log in.

\n\n\n\n

Obviously, you shouldn’t hardcode any sensitive information into your JavaScript code, since then it would be accessible to anyone whether they’re authenticated or not. This component is merely helpful for knowing when it’s safe to proceed with rendering components that depend on the user being logged in to work properly, such as the ProfileForm component.

\n\n\n\n

UnAuthContent

\n\n\n\n

This component simply does the opposite of the AuthContent component. If the user is unauthenticated, the children nested inside of this component are rendered and the user is allowed to stay on this page. Authenticated users are redirected to the /members page.

\n\n\n\n

Features

\n\n\n\n

Now that we understand how authentication is being done and how the useAuth() hook and AuthContent & UnAuthContent components can help us, let’s peruse the app’s features.

\n\n\n\n

Nav

\n\n\n\n

This component lives in components/Nav.tsx. it calls useAuth() to get the loggedIn value for the current user. It uses that to do some conditional rendering; logged-out users are shown some navigation links, whereas logged-in users are shown others.

\n\n\n\n

Log In

\n\n\n\n

You can navigate to /log-in to see this page, and open pages/log-in.tsx to view its code.

\n\n\n\n

\n\n\n\n

The page contents are wrapped in the <UnAuthContent> component to ensure that only unauthenticated users can view the Log In form.

\n\n\n\n

You can find the code for the LogInForm component in components/LogInForm.tsx.

\n\n\n\n

const LOG_IN = gql`\n  mutation logIn($login: String!, $password: String!) {\n    loginWithCookies(input: {\n      login: $login\n      password: $password\n    }) {\n      status\n    }\n  }\n`;\n\nexport default function LogInForm() {\n  const [logIn, { loading, error }] = useMutation(LOG_IN, {\n    refetchQueries: [\n      { query: GET_USER }\n    ],\n  });\n\n  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {\n    event.preventDefault();\n    const data = new FormData(event.currentTarget);\n    const { email, password } = Object.fromEntries(data);\n    logIn({\n      variables: {\n        login: email,\n        password,\n      }\n    }).catch(error => {\n      console.error(error);\n    });\n  }\n\n  return (\n    <form method=\"post\" onSubmit={handleSubmit}>\n      {/* etc. */}\n    </form>\n  );\n}

\n\n\n\n

It renders out the form and fires off the logIn mutation when the user submits it. It also displays any errors that come back in the response.

\n\n\n\n

If the log in is successful, it tells Apollo Client to refetch the GET_USER query (defined in hooks/useAuth.tsx). This results in the user being navigated away from this unauthenticated-users-only page and over to the /members page.

\n\n\n\n

This Log In form asks for the user’s email address, but you could modify that to instead ask for their WordPress login (a.k.a. their “username”) instead, if desired. Either one works with the loginWithCookies mutation.

\n\n\n\n

Log Out

\n\n\n\n

If you visit /log-out, the code in pages/log-out.tsx runs.

\n\n\n\n

const LOG_OUT = gql`\n  mutation logOut {\n    logout(input: {}) {\n      status\n    }\n  }\n`;\n\nexport default function LogOut() {\n  const [logOut, { called, loading, error, data }] = useMutation(LOG_OUT, {\n    refetchQueries: [\n      { query: GET_USER }\n    ],\n  });\n  const loggedOut = Boolean(data?.logout?.status);\n\n  useEffect(() => {\n    logOut();\n  }, [logOut]);\n\n  return (\n    <Layout>\n      <h1>Log Out</h1>\n      {!called || loading ? (\n        <p>Logging out...</p>\n      ) : error ? (\n        <p>{error.message}</p>\n      ) : !loggedOut ? (\n        <p>Unable to log out. Please reload the page and try again.</p>\n      ) : (\n        <p>You have been logged out.</p>\n      )}\n    </Layout>\n  );\n}

\n\n\n\n

When the useEffect() callback runs, the logOut mutation is executed to log the user out.

\n\n\n\n

Different messages are rendered to the page depending on whether the mutation has not yet completed, an error has occurred, or the user was successfully logged out.

\n\n\n\n

This code is implemented so that as soon as the user hits the Log Out page, they are logged out. As an alternative approach, you could have users click a Log Out button in your app, execute the logOut mutation, and then once they’re logged out, navigate them to another page and present them with a “You have been logged out” confirmation message. Either way works.

\n\n\n\n

New User Sign-up

\n\n\n\n

You can visit /sign-up as an unauthenticated user to test out this feature. It allows new users to register an account on the site.

\n\n\n\n

Note that users will only be able to sign up if the Anyone can register box is checked on the Settings > General page in theWordPress admin. Otherwise, if new user registrations are disabled, users will see a “User registration is currently not allowed” error message when attempting to submit the form.

\n\n\n\n

\n\n\n\n

The user flow goes like this:

\n\n\n\n

User visits /sign-up, fills out the form and clicks the button to sign up.
They see a message telling them a confirmation email has been sent to them.
User opens that email and clicks the link, which sends them back to the /set-password page in the Next.js app. The link includes key and login query string parameters, which are required for setting a user password.
User types their password into the Password and Confirm Password fields and hits the button to set it.
If an error occurred, such as if the link is old and no longer valid, the user will see error text.
Otherwise, if the new user’s password was successfully set, they see a Your new password has been set confirmation message and a link they can click to go to the Log In page.

\n\n\n\n

This is the SignUpForm component that provides that functionality:

\n\n\n\n

const REGISTER_USER = gql`\n  mutation registerUser(\n    $email: String!\n    $firstName: String!\n    $lastName: String!\n  ) {\n    registerUser(\n      input: {\n        username: $email\n        email: $email\n        firstName: $firstName\n        lastName: $lastName\n      }\n    ) {\n      user {\n        databaseId\n      }\n    }\n  }\n`;\n\nexport default function SignUpForm() {\n  const [register, { data, loading, error }] = useMutation(REGISTER_USER);\n  const wasSignUpSuccessful = Boolean(data?.registerUser?.user?.databaseId);\n\n  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {\n    event.preventDefault();\n    const data = new FormData(event.currentTarget);\n    const values = Object.fromEntries(data);\n    register({\n      variables: values,\n    }).catch(error => {\n      console.error(error);\n    });\n  }\n\n  if (wasSignUpSuccessful) {\n    return (\n      <p>\n        Thanks! Check your email – an account confirmation link has been sent to you.\n      </p>\n    )\n  }\n\n  return (\n    <form method=\"post\" onSubmit={handleSubmit}>\n      {/* etc. */}\n    </form>\n  );\n}

\n\n\n\n

Set Password Link

\n\n\n\n

The link in this email that users must click to set their password is generated by the Headless WordPress Email Settings plugin. It follows this format:

\n\n\n\n

\"https://frontend-js-app.com/set-password/?key={$key}&login={$login}\"

\n\n\n\n

When clicked, it will send users to the /set-password page of your frontend JS app where they can set their password. It also includes the key and login query string parameters, which WordPress requires to set a new password.

\n\n\n\n

Set Password Form

\n\n\n\n

The SetPasswordForm component (components/SetPasswordForm.tsx) that allows the user to set a password looks like this:

\n\n\n\n

const RESET_PASSWORD = gql`\n  mutation resetUserPassword(\n    $key: String!\n    $login: String!\n    $password: String!\n  ) {\n    resetUserPassword(\n      input: {\n        key: $key\n        login: $login\n        password: $password\n      }\n    ) {\n      user {\n        databaseId\n      }\n    }\n  }\n`;\n\nexport default function SetPasswordForm({ resetKey: key, login }: Props) {\n  const [password, setPassword] = useState('');\n  const [passwordConfirm, setPasswordConfirm] = useState('');\n  const [clientErrorMessage, setClientErrorMessage] = useState('');\n  const [resetPassword, { data, loading, error }] = useMutation(RESET_PASSWORD);\n  const wasPasswordReset = Boolean(data?.resetUserPassword?.user?.databaseId);\n\n  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {\n    event.preventDefault()\n    const isValid = validate();\n    if (!isValid) return\n\n    resetPassword({\n      variables: {\n        key,\n        login,\n        password,\n      },\n    }).catch(error => {\n      console.error(error);\n    });\n  }\n\n  function validate() {\n    // etc.\n  }\n\n  if (wasPasswordReset) {\n    return (\n      <>\n        <p>Your new password has been set.</p>\n        <Link href=\"/log-in\">\n          <a>Log in</a>\n        </Link>\n      </>\n    );\n  }\n\n  return (\n    <form method=\"post\" onSubmit={handleSubmit}>\n      {/* etc. */}\n    </form>\n  );\n}

\n\n\n\n

When the form is submitted and the field values pass validation, the resetUserPassword mutation is executed to perform the password reset.

\n\n\n\n

Password Strength Validation

\n\n\n\n

SetPasswordForm contains a validate() function that is called before the mutation gets fired off to set the user’s password. Currently, it ensures that the Password and Confirm Password values match, and that the password is at least 5 characters long. So just know that with the current implementation, a user would be able to set a very weak password, such as “12345”.

\n\n\n\n

If desired, you can use something like zxcvbn to enforce strong passwords on the client-side, and/or a WordPress plugin that enforces strong passwords on the server-side.

\n\n\n\n

Password Resets

\n\n\n\n

As a logged-out user, click the “Forgot password?” link below the Log In form to be navigated to the /forgot-password page.

\n\n\n\n

The password reset user flow goes like this:

\n\n\n\n

User enters their email address and clicks the Send password reset email button.
If an error occurs, such as if there is no user with that email address, error text will be displayed.
If the password reset email was successfully sent, the form is replaced with a success message telling the user to check their email.
User opens that email and clicks the link, which sends them back to the /set-password page in the Next.js app. The link includes key and login query string parameters, which are required for setting a user password.
User types their password into the Password and Confirm Password fields and hits the button to set it.
If an error occurred, such as if the link is old and no longer valid, the user will see error text.
Otherwise, if the new user’s password was successfully set, they see a Your new password has been set confirmation message and a link they can click to go to the Log In page.

\n\n\n\n

\n\n\n\n

You may have noticed that steps 4-7 on this list are identical to steps 3-6 of the New User Sign-up flow. That’s because the /set-password page and the SetPasswordForm component are used for both new user signups and for password resets.

\n\n\n\n

The /forgot-password page component (pages/forgot-password.tsx) renders the SendPasswordResetEmailForm component (components/SendPasswordResetEmailForm.tsx).

\n\n\n\n

const SEND_PASSWORD_RESET_EMAIL = gql`\n  mutation sendPasswordResetEmail($username: String!) {\n    sendPasswordResetEmail(\n      input: { username: $username }\n    ) {\n      user {\n        databaseId\n      }\n    }\n  }\n`;\n\nexport default function SendPasswordResetEmailForm() {\n  const [sendPasswordResetEmail, { loading, error, data }] = useMutation(\n    SEND_PASSWORD_RESET_EMAIL\n  );\n  const wasEmailSent = Boolean(data?.sendPasswordResetEmail?.user?.databaseId);\n\n  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {\n    event.preventDefault();\n    const data = new FormData(event.currentTarget);\n    const { email } = Object.fromEntries(data);\n    sendPasswordResetEmail({\n      variables: {\n        username: email,\n      }\n    }).catch(error => {\n      console.error(error);\n    });\n  }\n\n  if (wasEmailSent) {\n    return (\n      <p> Please check your email. A password reset link has been sent to you.</p>\n    );\n  }\n\n  return (\n    <form method=\"post\" onSubmit={handleSubmit}>\n      {/* etc. */}\n    </form>\n  );\n}

\n\n\n\n

You can see that when the user submits the form, the sendPasswordResetEmail mutation is executed. If it is successful, the form gets replaced with the confirmation message telling the user to check their email. They can then click the link in the email to be sent to the /set-password page and perform the reset.

\n\n\n\n

User Profile Page

\n\n\n\n

As a logged in user, you can head over to the /profile page to view and edit your user profile information.

\n\n\n\n

The ProfileForm component that provides this functionality is in components/ProfileForm.tsx.

\n\n\n\n

const UPDATE_PROFILE = gql`\n  mutation updateProfile(\n    $id: ID!\n    $firstName: String!,\n    $lastName: String!,\n    $email: String!\n  ) {\n    updateUser(input: {\n      id: $id\n      firstName: $firstName\n      lastName: $lastName\n      email: $email\n    }) {\n      user {\n        databaseId\n      }\n    }\n  }\n`;\n\nexport default function ProfileForm() {\n  const { user } = useAuth();\n  const { id, firstName, lastName, email } = user as User;\n  const [updateProfile, { data, loading, error }] = useMutation(UPDATE_PROFILE);\n  const wasProfileUpdated = Boolean(data?.updateUser?.user?.databaseId);\n\n  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {\n    event.preventDefault();\n    const data = new FormData(event.currentTarget);\n    const values = Object.fromEntries(data);\n    updateProfile({\n      variables: { id, ...values, },\n    }).catch(error => {\n      console.error(error);\n    });\n  }\n\n  return (\n    <form method=\"post\" onSubmit={handleSubmit}>\n      {wasProfileUpdated ? (\n        <p className=\"profile-update-confirmation\">\n          ✅ Profile details have been updated.\n        </p>\n      ) : null}\n      {/* etc. */}\n    </form>\n  );\n}

\n\n\n\n

When the user submits this form, the updateProfile mutation is fired off, which updates their information in the WordPress database. A success message is then displayed at the top of the form.

\n\n\n\n

You can try submitting this form, then viewing that user’s profile page in the WordPress admin to see the modified first name, last name, and/or email details reflected there.

\n\n\n\n

Members Page

\n\n\n\n

This page’s content is only visible to authenticated users. The app treats this page as the “home base” for logged-in users. Users are sent here immediately after logging in, and are also automatically redirected here if they attempt to visit a page that’s only for logged-out users, such as the /log-in page.

\n\n\n\n

Create Post

\n\n\n\n

You know how I said this blog post is only about authentication? I lied! ????

\n\n\n\n

The /create-post page gets into authorization. That is, it checks to see if the user has the publish_posts capability. If they do, the CreatePostForm component is rendered. If not, a message is displayed to let them know they don’t have the permissions necessary to create posts.

\n\n\n\n

export default function CreatePost() {\n  const { user } = useAuth();\n  const canCreatePosts = Boolean(user?.capabilities?.includes('publish_posts'));\n\n  return (\n    <Layout>\n      <AuthContent>\n        <h1>Create Post</h1>\n        {canCreatePosts ? (\n          <CreatePostForm />\n        ) : (\n          <p>You don&#39;t have the permissions necessary to create posts.</p>\n        )}\n      </AuthContent>\n    </Layout>\n  );\n}

\n\n\n\n

CreatePostForm is in components/CreatePostForm.tsx and looks like this:

\n\n\n\n

const CREATE_POST = gql`\n  mutation createPost($title: String!, $content: String!) {\n    createPost(input: {\n      title: $title\n      content: $content\n      status: PUBLISH\n    }) {\n      post {\n        databaseId\n      }\n    }\n  }\n`;\n\nexport default function CreatePostForm() {\n  const [createPost, { data, loading, error }] = useMutation(CREATE_POST);\n  const wasPostCreated = Boolean(data?.createPost?.post?.databaseId);\n\n  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {\n    event.preventDefault();\n    const data = new FormData(event.currentTarget);\n    const values = Object.fromEntries(data);\n    createPost({\n      variables: values\n    }).catch(error => {\n      console.error(error);\n    });\n  }\n\n  if (wasPostCreated) {\n    return (\n      <p>Post successfully created.</p>\n    );\n  }\n\n  return (\n    <form method=\"post\" onSubmit={handleSubmit}>\n      {/* etc. */}\n    </form>\n  )\n}

\n\n\n\n

When the user submits the form, the createPost mutation is fired off to create the post.

\n\n\n\n

Go ahead and try to log in as a user with the publish_posts capability (WP’s built-in Author, Editor or Administrator roles should work fine), and submit the form to create a new post. You can then visit the Posts page in the WordPress admin to see your newly created post on the list.

\n\n\n\n

But…why?

\n\n\n\n

You may be wondering: “Why would I want users who create blog posts to do so from my decoupled JS app? Shouldn’t they do that from the WordPress admin instead?”. You’re right– having content creators write blog posts from the WordPress admin makes much more sense. You may want users to be able to create some custom post types (CPT) posts from your frontend app, however. Here’s an example:

\n\n\n\n

Let’s say I have an educational site where students can create an account, take a course, then leave a review. I register a Review custom post type in WordPress, and register a Student user role, which is assigned the publish_review capability. In my decoupled JS application, I set it up so that logged-in students who have the publish_review capability are able to fill out a Course Review form. When they submit the form, a new Review CPT post is created in WordPress to capture that information. The student is then presented with a “Thanks for leaving a review!” message.

\n\n\n\n

Shared Cookies & Admin Access

\n\n\n\n

You might have noticed that:

\n\n\n\n

When you’re logged into the frontend JS app, you’re also logged into the WordPress admin and vice versa.
When you’re logged out of the frontend JS app, you’re also logged out of the WordPress admin and vice versa.

\n\n\n\n

This happens because the same cookie is being used in both places to authenticate you.

\n\n\n\n

Control WordPress Admin Access

\n\n\n\n

If you want to use native WordPress cookies to authenticate the users of your frontend JS app, but never want them to be able to log into the WordPress admin, you can use this WordPress plugin:

\n\n\n\n

Headless WordPress Admin Access

\n\n\n\n

You can follow the steps in the readme to lock down access to the WordPress admin to only users with a certain role or capability.

\n\n\n\n

CRUD Operations

\n\n\n\n

We saw how on the /create-post page, our app allows users to create new posts. If you want to go further than that and build an app where users can view, create, edit, and delete Custom Post Type posts, check out this other video of mine that covers how to do CRUD (create, read, update, delete) operations in headless WordPress:
Post Type CRUD Operations for WPGraphQL

\n\n\n\n

How to Use in Production

\n\n\n\n

In order to use this authentication method in production, you need to do the following:

\n\n\n\n

WordPress Backend

\n\n\n\n

Install and activate the same plugins mentioned in the WordPress Backend Setup section, above.
From the WordPress admin sidebar, go to Graphql > Settings and click the CORS Settings tab.
Check the checkboxes next to these options:
– Send site credentials
– Enable login mutation
– Enable logout mutation
In the Extend \"Access-Control-Allow-Origin” header field, enter the URL of your decoupled frontend JS app and click the button to save your changes.

\n\n\n\n

Next.js Frontend

\n\n\n\n

In the UI that your frontend JS app hosting company provides, define an environment variable named NEXT_PUBLIC_WORDPRESS_API_URL. Set its value to the GraphQL endpoint for your headless WordPress backend. For example: https://api.my-cool-site.com/graphql

\n\n\n\n

Wrapping Up

\n\n\n\n

I hope this blog post and the code repos provided give you a strong foundation for building headless WordPress projects that use WordPress’ native cookies for authentication.

\n\n\n\n

Please reach out to let us know what cool things you’re able to create!

\n","slug":"headless-wordpress-authentication-native-cookies","uri":"/headless-wordpress-authentication-native-cookies/"},{"__typename":"Post","id":"cG9zdDoyMTE=","slug":"gravity-forms-in-headless-wordpress-gatsby","seo":{"__typename":"PostTypeSEO","readingTime":12,"title":"Gravity Forms in Headless WordPress with Gatsby - WP Engine Developers"},"title0":"Gravity Forms in Headless WordPress with Gatsby","uri":"/gravity-forms-in-headless-wordpress-gatsby/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}}}},"content0":"\n

A couple weeks ago, I wrote a Gravity Forms in Headless WordPress blog post, and recorded a YouTube video to accompany it. They were both well received, but several members of the headless WordPress community told me that they’d love to learn how to work with Gravity Forms in a Gatsby app, specifically.

\n\n\n\n

In this post, we’ll learn how we can use WPGraphQL, and WPGraphQL for Gravity Forms on a headless WordPress back-end to send and receive Gravity Forms data to/from a decoupled front-end Gatsby application. We’ll see how we can use the unified GraphQL data layer that Gatsby provides to query for our form data at buildtime, then use Apollo Client to submit form entries from the client.

\n\n\n\n

In the Gatsby app repo, I’ll provide a suite of React components and a React hook that you can even drop into your Gatsby projects and have Gravity Forms “just work.” They’ll handle rendering out Gravity Forms forms and sending form submissions to your headless WordPress back-end.

\n\n\n\n

Let’s roll! 🏎💨

\n\n\n\n

Getting Started

\n\n\n\n

To benefit from this post, you should be familiar with the basics of working with the command line, local WordPress development, React, Gatsby, and Apollo Client.

\n\n\n\n

Here are the steps for getting set up:

\n\n\n\n

Set up a local WordPress site and get it running
Install and activate the Gravity Forms, WPGatsby, WPGraphQL and WPGraphQL for Gravity Forms WordPress plugins.
Clone down the Gatsby app repo for this project.
Import the form questionnaire form. From the WordPress admin sidebar, go to Forms > Import/Export > Import Forms. Select the gravityforms-questionnaire-form.json inside Gatsby app’s folder and click the button to import it.
Create an .env.development file inside of the Gatsby app’s folder. Open that file in a text editor and paste in GATSBY_WORDPRESS_API_URL=http://wpgraphqlgravtyforms.local/graphql, replacing wpgraphqlgravtyforms.local with the domain for your local WordPress site. This is the endpoint that both Gatsby and Apollo Client will use when they send requests to your WordPress back-end.
Run npm install or yarn to install the dependencies.
Run npm run develop to get the server running locally.
You should now be able to visit http://localhost:8000/ in a web browser and see the app’s homepage.

\n\n\n\n

How to Query for a Form

\n\n\n\n

The gatsby-source-wordpress source plugin used by our app takes the GraphQL schema that WPGraphQL and WPGraphQL for Gravity Forms provide and adds it to Gatsby’s unified GraphQL data layer. So querying for a form looks like this:

\n\n\n\n

query getForm {\n  wpGravityFormsForm(formId: {eq: 4}) {\n    formId\n    title\n    description\n    formFields {\n      nodes {\n        id\n        type\n        ... on WpTextField {\n          id\n          type\n          label\n        }\n        ... on WpSelectField {\n          id\n          type\n          label\n          choices {\n            text\n            value\n          }\n        }\n      }\n    }\n  }\n}

\n\n\n\n

You can see that we’re asking for some data about the form itself; namely, its formId, title and description. Then under formFields > nodes (which is a GraphQL interface), we use the ... on syntax to tell GraphQL what data we’d like back for each type of field. Any field types we include here will have data returned if they exist in the form, and any we have omitted will not– they’ll appear as empty objects instead.

\n\n\n\n

We can test out this query right from the GraphiQL IDE that Gatsby provides. Here’s how:

\n\n\n\n

With the app running, head over to http://localhost:8000/___graphql.
Paste the query above into the left column, replacing “4” in eq: 4 with the ID of the form you imported.
Click the ▶ button to execute the query.
See the results returned in the right column.

\n\n\n\n

\n\n\n\n

Check out the WPGraphQL for Gravity Forms readme for more documentation on this query, as well as other queries and mutations the plugin offers. Just note that many of the fields will have different names and input fields (such as wpGravityFormsForm instead of gravityFormsForm). That’s because Gatsby modifies the WPGraphQL schema a bit before adding it to its unified GraphQL data layer schema.

\n\n\n\n

Query for a Form in our App

\n\n\n\n

Now that we know what a query for a form looks like let’s see how we can use it in our Gatsby app.

\n\n\n\n

Open up gatsby-node.js.

\n\n\n\n

const path = require(\"path\");\n\nexports.createPages = async ({ actions }) => {\n  const { createPage } = actions;\n  const questionnaireTemplate = path.resolve(`src/templates/questionnaire.tsx`);\n\n  // Create Questionnaire page, and pass the Gravity Forms form ID to it.\n  createPage({\n    path: `/questionnaire`,\n    component: questionnaireTemplate,\n    context: {\n      formId: 4,\n    },\n  });\n};

\n\n\n\n

Notice that we call the createPage() function to tell Gatsby to create a page at /questionnaire using the src/templates/questionnaire.tsx template, and that we pass in a formId of 4 for the component’s context.

\n\n\n\n

Go ahead and swap out this form ID with the ID of the form you imported.

\n\n\n\n

Now try restarting the local dev server, then navigating to http://localhost:8000/questionnaire. You should see the form’s title, description and fields displayed in all their barely-even-styled-at-all glory! ????

\n\n\n\n

But where’s all this form data-fetching magic happening? Let’s dig a bit deeper. Open up the src/templates/questionnaire.tsx. page template.

\n\n\n\n

export default function Questionnaire({ data }: Props) {\n  const { wpGravityFormsForm: form } = data;\n\n  return (\n    <main>\n      <h1>{form.title}</h1>\n      <p>{form.description}</p>\n      <GravityForm form={form} />\n    </main>\n  );\n}\n\nexport const query = graphql`\n  query getForm($formId: Int!) {\n    wpGravityFormsForm(formId: { eq: $formId }) {\n      ...GravityFormFields\n    }\n  }\n`;

\n\n\n\n

You’ll see that we’re exporting a graphql tagged template literal containing our getForm GraphQL query. It accepts formId as an argument, then fetches the form with that ID.

\n\n\n\n

The ...GravityFormFields syntax makes use of this GraphQL fragment defined in src/components/GravityFormsForm.tsx:

\n\n\n\n

export const GRAVITY_FORM_FIELDS = graphql`\n  fragment GravityFormFields on WpGravityFormsForm {\n    formId\n    title\n    description\n    button {\n      text\n    }\n    confirmations {\n      isDefault\n      message\n    }\n    formFields {\n      nodes {\n        id\n        type\n        ...AddressFieldFields\n        ...CheckboxFieldFields\n        # etc.\n      }\n    }\n  }\n`;

\n\n\n\n

It specifies what data we want to fetch for the form. Inside, it leverages even more fragments– one for each type of field. You can see those individual field fragments in each file inside of the src/components/GravityFormsFields folder.

\n\n\n\n

These GraphQL fields could have all been hardcoded in the src/templates/questionnaire.tsx file, but using GraphQL fragments allows us to co-locate each component’s data requirements with that component itself. That way, things are more organized.

\n\n\n\n

Render the Form

\n\n\n\n

Now that we know how the form data is being queried and passed into the Questionnaire page component, let’s see how we can use that data to render our form.

\n\n\n\n

Head back over to src/templates/questionnaire.tsx. You’ll see that the form’s title and description render inside of h1 and p tags, respectively, and then a <GravityForm /> component is rendered, with the form passed to it as a prop:

\n\n\n\n

<main>\n  <h1>{form.title}</h1>\n  <p>{form.description}</p>\n  <GravityForm form={form} />\n</main>

\n\n\n\n

Open src/components/GravityForm.tsx, where the GravityForm component is defined, and you’ll see that it renders a GravityFormsForm component, which is wrapped in a GravityFormProvider context provider:

\n\n\n\n

<GravityFormProvider>\n  <GravityFormsForm {...props} />\n</GravityFormProvider>

\n\n\n\n

Don’t worry about GravityFormProvider just yet– we’ll learn about that in the next section. For now, let’s focus on the GravityFormsForm component rendered inside of it. Navigate to src/components/GravityFormsForm.tsx next.

\n\n\n\n

GravityFormsForm accepts form as a prop and renders an HTML <form> element with the form fields, any error messages, and the submit button inside. You’ll notice that it also contains a handleSubmit function to serve as the onSubmit event handler for our form. When the form is submitted, the submitForm mutation (defined at the top of the file) executes with formId and fieldValues passed in as variables.

\n\n\n\n

Next, let’s take a look at how our fields are rendering. Inside of the <form>, we map over the formFields and render a GravityFormsField component for each field:

\n\n\n\n

{formFields.map(field =>\n  <GravityFormsField\n    key={field?.id}\n    field={field as FormField}\n    fieldErrors={getFieldErrors(Number(field?.id))}\n  />\n)}

\n\n\n\n

Let’s keep following this trail and head over to src/components/GravityFormsField.tsx to check out the GravityFormsField component. You’ll see that it’s little more than a switch() statement:

\n\n\n\n

export default function GravityFormsField({ field, fieldErrors }: Props) {\n  switch (field.type) {\n    case \"address\":\n      return <AddressField field={field} fieldErrors={fieldErrors} />;\n    case \"checkbox\":\n      return <CheckboxField field={field} fieldErrors={fieldErrors} />;\n    case \"date\":\n      return <DateField field={field} fieldErrors={fieldErrors} />;\n    // etc.\n  }\n}

\n\n\n\n

The appropriate field component is rendered out, depending on the value of field.type. When field.type encounters an unsupported field, a “Field type not supported” message appears instead.

\n\n\n\n

Render the Fields

\n\n\n\n

From here, you can peruse all of the individual field components inside of the src/components/GravityFormsFields folder to see how they work. All of them follow the same pattern. They:

\n\n\n\n

Define their data requirements in an exported GraphQL fragment (which get leveraged inside of src/components/GravityFormsForm.tsx, as mentioned previously)
Define the field component, which accepts these props:
– field (the data about this field)
– fieldErrors (any errors specific to this field)
…and returns JSX for the field
Use the useGravityForm() custom React hook and
– Use its state object to get the current value for this field
– Call its dispatch function to update the field’s value in state

\n\n\n\n

“Wait, where in blazes did this custom useGravityForm() React hook come from?!”
– You, just now

\n\n\n\n

I’m glad you asked! Let’s find out –

\n\n\n\n

Managing our Form State

\n\n\n\n

Remember earlier when we saw that GravityFormProvider context provider in src/components/GravityForm.tsx? That, and the custom useGravityForm() hook are defined in src/hooks/useGravityForm.tsx. Let’s take a look at that file next to understand better how to manage our form state.

\n\n\n\n

Scroll down to GravityFormProvider. This is a React context provider that uses React’s useReducer() and passes down state and dispatch as its value:

\n\n\n\n

export function GravityFormProvider({ children }: { children: ReactNode }) {\n  const [state, dispatch] = useReducer(reducer, DEFAULT_STATE);\n\n  return (\n    <GravityFormContext.Provider value={{ state, dispatch }}>\n      {children}\n    </GravityFormContext.Provider>\n  );\n}

\n\n\n\n

When dispatch() is called from inside of our field components, the reducer() function in this file determines how the form state should update. The reducer runs a switch() on the type of action that was dispatched and updates the form state accordingly using the action.fieldValue data that passed in:

\n\n\n\n

switch (action.type) {\n  case ACTION_TYPES.updateAddressFieldValue: {\n    const { id, addressValues } = action.fieldValue as AddressFieldValue;\n    return [...getOtherFieldValues(id), { id, addressValues }];\n  }\n  case ACTION_TYPES.updateCheckboxFieldValue: {\n    const { id, checkboxValues } = action.fieldValue as CheckboxFieldValue;\n    return [...getOtherFieldValues(id), { id, checkboxValues }];\n  }\n  // etc.\n}

\n\n\n\n

Submitting Forms

\n\n\n\n

Try submitting a few form entries yourself. After the form submits, it will be removed from the UI and replaced with the “thank you” confirmation message for our form.

\n\n\n\n

Back in the WordPress admin, you can navigate to the Gravity Forms Entries page for our form and see your new entries listed. Try clicking on a few of them and confirming that the saved values match what you had entered into the form.

\n\n\n\n

Error Handling

\n\n\n\n

Our Gatsby app handles two types of errors:

\n\n\n\n

Request or Server Errors

\n\n\n\n

These are errors that prevent the form entry from being saved. Some examples:

\n\n\n\n

The user’s network connection dropped out
The WordPress back-end threw a 500 Internal Server Error
The request was rejected because only logged-in users with the proper permissions are allowed to submit form entries for that particular form

\n\n\n\n

If any of these errors occur, Apollo Client will return an error object. Our app will display errors at the bottom of the form if errors exist, just above the submit button.

\n\n\n\n

To see this error handling in action, you can set your network connection to offline in the browser DevTools and then attempt to submit the form while offline.

\n\n\n\n

Field Validation Errors

\n\n\n\n

Inside the GravityFormsForm component, we check data.submitGravityFormsForm.errors to see if the server returns any validation errors. If we have field validation errors, we call the getFieldErrors() helper function to pull out the errors and pass them through to that particular field that failed validation. The error message text is displayed directly below that field, so the user knows why the field value they entered is invalid.

\n\n\n\n

To test this locally, you can use the “Short Strings Only” field at the bottom of the imported form. In the Gravity Forms admin UI, we’ve configured that field to allow strings with a maximum length of 5 characters. So if you enter more than five characters into it, then try to submit the form, you’ll see the field validation error text appear below that field.

\n\n\n\n

What’s Missing?

\n\n\n\n

This suite of React components and custom hook are a starting point. You can drop them into your project and get up and running with Gravity Forms forms quickly in a Gatsby app, but there are some features they don’t provide. Some examples:

\n\n\n\n

Client-side validation (beyond the built-in validation the browser performs on simple, single-input fields)
Support for Gravity Forms’ Conditional Logic rules
Rendering an existing Gravity Forms entry and allowing the user to update its field values
Support for all field types (see the section below for more details)

\n\n\n\n

Which Fields are Supported?

\n\n\n\n

We’re using the submitGravityFormsForm mutation that WPGraphQL for Gravity Forms provides to keep things simple. This mutation works excellent for allowing us to submit forms with some field types, such as inside of our project’s src/components/GravityFormsFields folder. However, it does not work for all field types that the WPGraphQL for Gravity Forms plugin supports.

\n\n\n\n

If you want to use other field types, you would instead need to implement a more complex process that involves firing off multiple mutations to build a draft entry incrementally, then finally submit it. This is because currently, the GraphQL specification does not support input union types. You can learn more about that technical limitation by reading this GitHub issue thread and more about the alternative submission process in the WPGraphQL for Gravity Forms readme.

\n\n\n\n

Hide Unsupported Fields in the WordPress Admin

\n\n\n\n

Since not all field types support this approach, you may want to limit the Gravity Forms fields displayed in the WordPress admin to only the supported ones. This way, you’ll know that the content creators on the site can only choose fields that the headless app supports. You can do that using this plugin I wrote:

\n\n\n\n

Gravity Forms Fields Allowlist

\n\n\n\n

Just modify the list of ALLOWED_FIELDS inside of gravityforms-fields-allowlist.php to include the ones you want to be displayed in the WordPress admin, then install and activate the plugin.

\n\n\n\n

How Can I Use This in My Gatsby Projects?

\n\n\n\n

Copy and paste src/hooks/useGravityForm.tsx, and all the components inside of src/components into your codebase.
Mimic the code in gatsby-node.js to create a new page and pass in a formId as context to that page component.
Copy the exported graphql query in src/templates/questionnaire.tsx and paste it into your page component file.
Inside of the page component that receives the data.wpGravityFormsForm prop, render the <GravityForm form={form} /> component.
If you’re using TypeScript, set up GraphQL Code Generator to generate the TypeScript types stored in generated/graphql.ts and used throughout this app. A video and blog post are available that walk through this process.

\n\n\n\n

Wrapping Up

\n\n\n\n

Thanks for sticking with me! I hope this post and the code repos provided are helpful as you implement Gravity Forms forms in your headless WordPress + Gatsby applications. Please reach out and let us know how it goes!

\n"},{"__typename":"Post","id":"cG9zdDoxOTc=","slug":"apollo-client-cache-rehydration-in-next-js","seo":{"__typename":"PostTypeSEO","readingTime":9,"title":"Apollo Client Cache Rehydration in Next.js - WP Engine Developers"},"title0":"Apollo Client Cache Rehydration in Next.js","uri":"/apollo-client-cache-rehydration-in-next-js/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}}}},"content0":"\n

Apollo Client is a popular GraphQL client that can cache the results of your queries, among many other features. If you have an entirely client-side rendered (CSR) front-end app and want to do all your data fetching in the browser, you can simply start off with an empty Apollo Client cache and populate it with data as GraphQL requests execute.

\n\n\n\n

But what if you want to use server-side rendering (SSR), static site generation (SSG), or incremental static regeneration (ISR), though? How can you fetch data ahead of time on the server? Can the Apollo Client’s cache initialize with that data on the client so that your queries don’t need to be rerun?

\n\n\n\n

Thankfully, there is a way to fetch data on the server, populate Apollo Client’s cache, send that cache data to the client, and use it to “rehydrate” or initialize Apollo Client’s cache in the browser. Cache rehydration gives the benefits of SSR/SSG/ISR (a fully rendered HTML document on the initial page load, great SEO, etc.). Best of all, you still have the data in Apollo Client’s cache. This prevents your app from making unnecessary network requests for data you already have.

\n\n\n\n

In this blog post, we’ll cover how to set up Apollo Client cache rehydration in a Next.js app.

\n\n\n\n

Project Setup

\n\n\n\n

Before setting up cache rehydration, fulfill the following prerequisites:

\n\n\n\n

Clone down the repo to your machine: https://github.com/kellenmace/apollo-client-cache-rehydration-in-next-js
Run npm install (or yarn) to install the project’s dependencies.
Create a .env.local file in the root directory with this variable defined: NEXT_PUBLIC_WORDPRESS_API_URL=http://my-local-site.local/graphql. Swap out http://my-local-site.local with the domain of a WordPress site that has WPGraphQL installed.
Run npm run dev to get the app up and running locally.

\n\n\n\n

Approach

\n\n\n\n

Server-side Rendering (SSR) through the Apollo client follows this approach:

\n\n\n\n

Use Apollo Client’s getDataFromTree() function to get the results for all queries throughout your entire component tree for the current page.
Extract Apollo Client’s cache and send that data to the client as a global window.APOLLO_STATE object.
When Apollo Client initializes on the client, call its new InMemoryCache().restore() function, passing in the window.APOLLO_STATE object to seed it with the cache data from the server.

\n\n\n\n

Although using the SSR approach works well with Next.js, the recommended way to do Apollo Client cache rehydration differs from that. We will instead do this:

\n\n\n\n

Use Next’s getStaticProps() or getServerSideProps() function to do our data fetching and populate Apollo Client’s cache.
Extract Apollo Client’s cache and add it as a pageProps prop for the current page.
When Apollo Client initializes on the client, call its new InMemoryCache().restore() function, passing in the cache data from the server.

\n\n\n\n

For more information on how the Apollo client works, check out this official Next.js example project. We’ll use that same approach for our purposes, except the code examples will be written in TypeScript rather than JS, and all the data fetching examples will be specific to WordPress and WPGraphQL.

\n\n\n\n

Install & Configure Apollo Client

\n\n\n\n

Per Apollo Client’s getting started documentation, the @apollo/client and graphql NPM are already installed. The deepmerge and lodash packages have also been installed, which our project leverages.

\n\n\n\n

To start configuring the client, open the lib/apolloClient.ts file in a code editor. It looks like this:

\n\n\n\n

import { useMemo } from 'react';\nimport { ApolloClient, HttpLink, InMemoryCache, NormalizedCacheObject } from '@apollo/client';\nimport { relayStylePagination } from \"@apollo/client/utilities\";\nimport merge from 'deepmerge';\nimport isEqual from 'lodash/isEqual';\n\nexport const APOLLO_STATE_PROP_NAME = '__APOLLO_STATE__';\n\nlet apolloClient: ApolloClient<NormalizedCacheObject> | undefined;\n\nfunction createApolloClient() {\n  return new ApolloClient({\n    ssrMode: typeof window === 'undefined',\n    link: new HttpLink({\n      uri: process.env.NEXT_PUBLIC_WORDPRESS_API_URL, // Server URL (must be absolute)\n      credentials: 'same-origin', // Additional fetch() options like `credentials` or `headers`\n    }),\n    cache: new InMemoryCache({\n      // typePolicies is not required to use Apollo with Next.js - only for doing pagination.\n      typePolicies: {\n        Query: {\n          fields: {\n            posts: relayStylePagination(),\n          },\n        },\n      },\n    }),\n  })\n}\n\nexport function initializeApollo(initialState: NormalizedCacheObject | null = null) {\n  const _apolloClient = apolloClient ?? createApolloClient();\n\n  // If your page has Next.js data fetching methods that use Apollo Client, the initial state\n  // gets hydrated here\n  if (initialState) {\n    // Get existing cache, loaded during client side data fetching\n    const existingCache = _apolloClient.extract();\n\n    // Merge the existing cache into data passed from getStaticProps/getServerSideProps\n    const data = merge(initialState, existingCache, {\n      // combine arrays using object equality (like in sets)\n      arrayMerge: (destinationArray, sourceArray) => [\n        ...sourceArray,\n        ...destinationArray.filter((d) =>\n          sourceArray.every((s) => !isEqual(d, s))\n        ),\n      ],\n    });\n\n    // Restore the cache with the merged data\n    _apolloClient.cache.restore(data);\n  }\n\n  // For SSG and SSR always create a new Apollo Client\n  if (typeof window === 'undefined') return _apolloClient;\n\n  // Create the Apollo Client once in the client\n  if (!apolloClient) apolloClient = _apolloClient;\n\n  return _apolloClient;\n}\n\nexport function addApolloState(client: ApolloClient<NormalizedCacheObject>, pageProps: any) {\n  if (pageProps?.props) {\n    pageProps.props[APOLLO_STATE_PROP_NAME] = client.cache.extract();\n  }\n\n  return pageProps;\n}\n\nexport function useApollo(pageProps: any) {\n  const state = pageProps[APOLLO_STATE_PROP_NAME];\n  const store = useMemo(() => initializeApollo(state), [state]);\n  return store;\n}

\n\n\n\n

Let’s walk through each of those function definitions.

\n\n\n\n

createApolloClient()

\n\n\n\n

This function is responsible for creating a new instance of Apollo Client.

\n\n\n\n

We set Apollo Client’s ssrMode option to true if the code is running on the server, and to false if it’s running on the client.

\n\n\n\n

The uri: process.env.NEXT_PUBLIC_WORDPRESS_API_URL line tells Apollo Client to use the GraphQL endpoint defined in your .env.local file for all network requests.

\n\n\n\n

initializeApollo()

\n\n\n\n

As its name suggests, this function initializes Apollo Client. It merges the initial state (data passed in from getStaticProps() / getServerSideProps()) with the existing client-side Apollo cache, then sets that new, merged data set as the new cache for Apollo Client.

\n\n\n\n

addApolloState()

\n\n\n\n

This function takes the pageProps returned from getStaticProps() / getServerSideProps() for the current page and adds to them Apollo’s cache data. From there, Next.js takes care of passing Apollo’s cache data, along with any other page-specific props into the page component.

\n\n\n\n

useApollo()

\n\n\n\n

This function calls initializeApollo() to get an instance of Apollo Client that has Apollo’s cache data added to it. This client is ultimately passed in as a prop to the ApolloProvider that Apollo Client provides.

\n\n\n\n

Render an ApolloProvider

\n\n\n\n

Inside of _app.tsx, we call useApollo() to get a new instance of Apollo Client, passing to it the pageProps for the current page. The apolloClient instance is then passed in as a prop to the ApolloProvider component, which wraps our application.

\n\n\n\n

import { AppContext, AppInitialProps } from \"next/app\";\nimport { ApolloProvider } from \"@apollo/client\";\nimport { useApollo } from \"../lib/apolloClient\";\n\nimport \"../styles/globals.css\";\n\nfunction MyApp({ Component, pageProps }: AppContext & AppInitialProps) {\n  const apolloClient = useApollo(pageProps)\n\n  return (\n    <ApolloProvider client={apolloClient}>\n      <Component {...pageProps} />\n    </ApolloProvider>\n  );\n}\n\nexport default MyApp;

\n\n\n\n

How to Use in Page Components

\n\n\n\n

Let’s see how we can use this Apollo Client cache rehydration superpower in our Next.js page components.

\n\n\n\n

Open up pages/ssg.tsx. A simplified version of that file looks like this:

\n\n\n\n

import { gql, useQuery } from \"@apollo/client\";\nimport { initializeApollo, addApolloState } from \"../lib/apolloClient\";\n\nconst POSTS_PER_PAGE = 10;\n\nconst GET_POSTS = gql`\n  query getPosts($first: Int!, $after: String) {\n    posts(first: $first, after: $after) {\n      # etc.\n    }\n  }\n`;\n\nexport default function SSG() {\n  const { loading, error, data } = useQuery(GET_POSTS, {\n    variables: {\n      first: POSTS_PER_PAGE,\n      after: null,\n    }\n  });\n\n  // etc.\n}\n\nexport async function getStaticProps(context: GetStaticPropsContext) {\n  const apolloClient = initializeApollo();\n\n  await apolloClient.query({\n    query: GET_POSTS,\n    variables: {\n      first: POSTS_PER_PAGE,\n      after: null,\n    }\n  });\n\n  return addApolloState(apolloClient, {\n    props: {},\n  });\n}

\n\n\n\n

Inside of Next.js’ getStaticProps() function, we call initializeApollo() to get an instance of Apollo Client that we can use for making GraphQL requests.

\n\n\n\n

We then call the apolloClient.query() method, passing in the exact same query and variables that are used inside of our SSG page component when it calls the useQuery() hook. You’ll notice that we’re not even using the return value that apolloClient.query() provides. This is because we don’t need it – we’re only calling apolloClient.query() to populate Apollo Client’s cache with the data for the queries executed.

\n\n\n\n

When our SSG page component is rendered in the browser and the useQuery() hook is called, Apollo Client will “see” that the data for the query being executed already exists it its cache, and will use that data instead of making a network request. This will result in the content on the page rendering immediately. Visit http://localhost:3000/ssg in your browser, open up the Network tab in the DevTools and refresh the page to confirm that no client-side GraphQL requests execute.

\n\n\n\n

More info on Next.js’ getStaticProps() function can be found here: https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation.

\n\n\n\n

SSR Page

\n\n\n\n

Open up pages/ssr.tsx and visit http://localhost:3000/ssr. You can see that this file functions exactly the same as ssg.tsx, except that Next.js passes in the page props on every request since we’re using getServerSideProps() instead of getStaticProps(). Again, you can open up the Network tab in the DevTools and refresh the page to confirm that no client-side GraphQL requests execute.

\n\n\n\n

More info on Next.js’ getServerSideProps() function can be found here: https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering.

\n\n\n\n

CSR Page

\n\n\n\n

To prove that we still have the option to do data fetching on the client, if desired, open up pages/csr.tsx and visit http://localhost:3000/csr. You can see that this page does not fetch any data on the server, since we’re not using getStaticProps() or getServerSideProps(). If you open up the Network tab in the DevTools and refresh the page, you can confirm that the GraphQL network requests execute client-side when the page first loads. You can do this if you want your request to run in the browser only, and not on the server.

\n\n\n\n

Mixed SSG + CSR Page

\n\n\n\n

Finally, open up pages/blog.tsx. Make sure you have eleven or more posts created in your WordPress backend, then visit http://localhost:3000/blog.You can see that inside of getStaticProps(), an Apollo Client query is executed to get the initial list of ten blog posts, which immediately get rendered to the page when it loads. If more posts exist in the WordPress backend, the user is presented with a Load more button. Clicking this button results in Apollo Client’s fetchMore() function being called, which fires off a network request to get the next five posts and appends them to the list. Once all posts have been loaded, the user sees an ✅ All posts loaded message.

\n\n\n\n

The blog.tsx page shows how you can fetch some data on the server to populate Apollo’s cache. Also, the markup appears instantly when the page loads on the front-end. After, the page fires subsequent client-side requests to fetch additional data, adding it to Apollo’s cache..

\n\n\n\n

How to Use this Code in Your Projects

\n\n\n\n

In order to use Apollo Client for SSG/SSR/ISR in a Next.js project, you’ll need to follow these steps:

\n\n\n\n

Copy lib/apolloClient.ts into your project.
As stated above, set the process.env.NEXT_PUBLIC_WORDPRESS_API_URL variable to reference the GraphQL endpoint of your headless WordPress backend.
The object containing typePolicies that is being passed into new InMemoryCache() in this file can be omitted if you’re not doing any pagination in your project (such as the fetchMore() pagination demonstrated on the pages/blog.tsx page).
In pages/_app.tsx, call useApollo(pageProps) to get an instance of Apollo Client, then pass that in as a prop to the <ApolloProvider /> component, as shown above.
Mimic the page components in the /pages directory of this project, depending on whether you want your pages to do their data fetching at build time (see ssg.tsx), at request time on the server (see ssr.tsx), on the client only (see csr.tsx), or a mixture of those (see blog.tsx).

\n\n\n\n

Wrapping Up

\n\n\n\n

I hope this walk-through helps you with leveraging Apollo Client for SSG/SSR/ISR data fetching on your next Next.js project.

\n\n\n\n

And that’s it! Thanks so much for giving this post a read, and please reach out to us with any questions you have! ????

\n"},{"__typename":"Post","id":"cG9zdDoxODY=","slug":"graphql-code-generator-for-wpgraphql","seo":{"__typename":"PostTypeSEO","readingTime":6,"title":"GraphQL Code Generator for WPGraphQL - WP Engine Developers"},"title0":"GraphQL Code Generator for WPGraphQL","uri":"/graphql-code-generator-for-wpgraphql/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}}}},"content0":"\n

When getting started with TypeScript, developers quickly become accustomed to defining their typings. For a React component that’s responsible for rendering a single blog post’s content, you may write something like this:

\n\n\n\n

type Avatar = {\n  url: string;\n};\n\ntype User = {\n  name: string;\n  avatar: Avatar;\n};\n\ntype Post = {\n  databaseId: number;\n  title: string;\n  slug: string;\n  excerpt: string;\n  content: string;\n  author: {\n    node: User;\n  }\n};\n\ntype Props = {\n  post: Post;\n};\n\nexport default function BlogPost(props: Props) {\n  const { post } = props;\n  return (\n    <article>\n      <h1>{post.title}</h1>\n      {/* etc. */}\n    </article>\n  );\n}

\n\n\n\n

You can see that the BlogPost component accepts an argument with a type of Props, which itself uses a type of Post. Post uses the User type, which in turn uses the Avatar type. Sure, you may be able to nest some of those types inside others to make things a bit more concise, but you still end up with quite a few type definitions. While this code works fine, you may find that it is time-consuming to create all the types for your project manually.

\n\n\n\n

If your project sources its data from a GraphQL API, you may look at the GraphQL schema and think:

\n\n\n\n

“Wait…since my GraphQL schema is strongly typed, can’t I just leverage those same types in my TypeScript code instead of reinventing the wheel?”

\n\n\n\n

You, my astute friend, are in luck! That is indeed possible using GraphQL Code Generator, a.k.a. “GraphQL Codegen.” This free, open-source tool can use your GraphQL schema to generate TypeScript typings. This image sums it up nicely:

\n\n\n\n

\n\n\n\n

Set Up

\n\n\n\n

Let’s learn how you set up GraphQL Codegen in your headless WordPress projects that use WPGraphQL.

\n\n\n\n

Enable GraphQL Introspection

\n\n\n\n

In the WordPress admin sidebar of your local environment, head to GraphQL > Settings. Make sure the Enable Public Introspection option is checked. This will allow GraphQL Code Generator to run an introspection query against your GraphQL endpoint to get the entire schema.

\n\n\n\n

\n\n\n\n

Initialize GraphQL Code Generator

\n\n\n\n

Head over to the GraphQL Code Generator Getting Started documentation page. Follow the steps for installing the graphql and @graphql-codegen/cli NPM packages.
Run npx graphql-codegen init (or yarn graphql-codegen init) to launch the initialization wizard. Below, we’ll cover what to enter for each prompt.

\n\n\n\n

What type of application are you building?

\n\n\n\n

Select Angular/React/any thing your heart desires.

\n\n\n\n

Where is your schema?

\n\n\n\n

Paste in your local WordPress site’s GraphQL endpoint. You can see it on the WPGraphQL settings page here:

\n\n\n\n

\n\n\n\n

Where are your operations and fragments?

\n\n\n\n

Enter the path to where the .graphql files containing operations and fragments. Example: src/**/*.graphql. If you don’t have .graphql files in your project, just hit enter to go to the next step.

\n\n\n\n

Pick plugins

\n\n\n\n

Make sure to check TypeScript (required by other typescript plugins. Look if TypeScript Operations (operations and fragments) only if you have .graphql files containing GraphQL operations and fragments in your project; un-check it, if not. Leave all other options unchecked and hit enter to continue.

\n\n\n\n

Where to write the output

\n\n\n\n

Enter generated/graphql.ts. This tells GraphQL Code Generator what file it should write the generated typings.

\n\n\n\n

Do you want to generate an introspection file?

\n\n\n\n

Choose “No”.

\n\n\n\n

How to name the config file?

\n\n\n\n

Hit enter to accept the default codegen.yml filename.

\n\n\n\n

What script in package.json should run the codegen?

\n\n\n\n

Enter generate.

\n\n\n\n

The GraphQL Codegen CLI will:

\n\n\n\n

Generate a codegen.yml configuration file based on your answers
Add a few NPM packages to your devDependencies to your project
Add a new generate script in package.json. You’ll be able to run whenever you want to generate your typings

\n\n\n\n

The command line output should look something like this:

\n\n\n\n

\n\n\n\n

Next, run npm install (or yarn) to install the new devDependencies.

\n\n\n\n

If you do not have .graphql files containing GraphQL operations and fragments in your project, remove the entire documents: line from codegen.yml and save the file. If you don’t do this, GraphQL Codegen will throw an error when you try to generate your typings since it will be unable to find those files.

\n\n\n\n

Generate Your Typings

\n\n\n\n

With typing set up complete , run npm run generate to generate your typings. GraphQL Code Generator will access the GraphQL schema via your local site’s GraphQL endpoint and generate TypeScript typings.

\n\n\n\n

Congrats! You have now used your GraphQL schema to generate TypeScript typings you can use in your frontend app! You can check out the generated/graphql.ts file to see all the generated typings.

\n\n\n\n

How to Use the Generated Types

\n\n\n\n

Let’s revisit our BlogPost component example from the beginning of this blog post. Rather than all of those type definitions we had created manually, we can instead do this:

\n\n\n\n

import { Post } from \"../../generated/graphql\";\n\ntype Props = {\n  post: Post;\n};\n\nexport default function BlogPost(props: Props) {\n  const { post } = props;\n  return (\n    <article>\n      <h1>{post.title}</h1>\n      {/* etc. */}\n    </article>\n  );\n}

\n\n\n\n

You can see that this is quite a bit simpler. Rather than creating our typings manually, we can leverage the ones that GraphQL Codegen generated for us.

\n\n\n\n

When to Generate Typings

\n\n\n\n

You can commit the generated/graphql.ts to your version control system so the generated types are stored alongside the rest of your project. Anytime you want to regenerate the types (such as if you make changes to the GraphQL schema or install a WPGraphQL extension), you can run npm run generate again. This will overwrite your current generated/graphql.ts file.

\n\n\n\n

Plugins & Integrations

\n\n\n\n

We’ve learned the basics of how to set up and run GraphQL Code Generator to generate typings using our GraphQL schema. If you want to go further and automatically generate even more code for your project, I encourage you to check out the GraphQL Code Generator plugins available.

\n\n\n\n

There are plugins available for Apollo Client, React Query, GraphQL Request. and other popular libraries that generate other things for you, such as custom React hooks, higher-order components, etc.

\n\n\n\n

Note for Gatsby users: an integration also exists to generate typings from Gatsby’s unified GraphQL data layer. See the documentation for details.

\n\n\n\n

Wrapping Up

\n\n\n\n

I hope this post is helps you understand the benefits you can gain by using GraphQL Code Generator to generate typings for your frontend JavaScript app based on your GraphQL schema. You should also have a good idea of how to set up GraphQL Codegen for your projects and run it to generate your types. Thanks for reading! ????

\n"}],"pageInfo":{"__typename":"WPPageInfo","hasNextPage":true,"endCursor":"YXJyYXljb25uZWN0aW9uOjE4Ng=="}},"seo":{"schema":{"siteUrl":"https://developers.wpengine.com","__typename":"SEOSchema","companyLogo":{"__typename":"MediaItem","id":"cG9zdDoxNjg=","altText":""},"siteName":"WP Engine Developers"},"__typename":"SEOConfig"}},"selections":[[["0-1-2","youtubeVideos0"],["3-1-4","posts0"],["5-6-7","avatar0"],["8-6-9","title0"],["10-11-12","post0"],["13-6-9","content0"],["14-15-16","headlessWordPressPlugins0"],["10-17-12","post1"],["10-18-12","post2"],["3-19-4","posts1"],["0-20-2","youtubeVideos1"],["10-21-12","post3"],["10-22-12","post4"],["10-23-12","post5"],["10-24-12","post6"],["10-25-12","post7"],["10-26-12","post8"],["0-27-2","youtubeVideos2"],["10-28-12","post9"],["10-29-12","post10"],["10-30-12","post11"],["10-31-12","post12"],["10-32-12","post13"],["10-33-12","post14"],["10-34-12","post15"],["10-35-12","post16"],["10-36-12","post17"],["10-37-12","post18"],["0-38-2","youtubeVideos3"],["0-39-2","youtubeVideos4"],["10-40-12","post19"],["10-41-12","post20"],["10-42-12","post21"],["10-43-12","post22"],["10-44-12","post23"]],[["youtubeVideos",0],["{\"first\":3}",1],["{\"first\":\"Int\",\"last\":\"Int\",\"after\":\"String\",\"before\":\"String\",\"where\":\"RootQueryToYoutubeVideoConnectionWhereArgs\"}",2],["posts",3],["{\"first\":\"Int\",\"last\":\"Int\",\"after\":\"String\",\"before\":\"String\",\"where\":\"RootQueryToPostConnectionWhereArgs\"}",4],["avatar",5],["{}",6],["{\"size\":\"Int\",\"forceDefault\":\"Boolean\",\"rating\":\"AvatarRatingEnum\"}",7],["title",8],["{\"format\":\"PostObjectFieldFormatEnum\"}",9],["post",10],["{\"id\":\"gutenberg-in-headless-wordpress-render-blocks-as-html\",\"idType\":\"SLUG\"}",11],["{\"id\":\"ID!\",\"idType\":\"PostIdType\",\"asPreview\":\"Boolean\"}",12],["content",13],["headlessWordPressPlugins",14],["{\"first\":500}",15],["{\"first\":\"Int\",\"last\":\"Int\",\"after\":\"String\",\"before\":\"String\",\"where\":\"RootQueryToHeadlessWordPressPluginConnectionWhereArgs\"}",16],["{\"id\":\"headless-wordpress-authentication-native-cookies\",\"idType\":\"SLUG\"}",17],["{\"id\":\"what-is-atlas-content-modeler\",\"idType\":\"SLUG\"}",18],["{\"first\":9}",19],["{\"first\":12}",20],["{\"id\":\"atlas-content-modeler-walk-through\",\"idType\":\"SLUG\"}",21],["{\"id\":\"apollo-client-cache-rehydration-in-next-js\",\"idType\":\"SLUG\"}",22],["{\"id\":\"gravity-forms-in-headless-wordpress-gatsby\",\"idType\":\"SLUG\"}",23],["{\"id\":\"work-with-gravity-forms-in-headless-wordpress\",\"idType\":\"SLUG\"}",24],["{\"id\":\"the-when-and-where-of-rendering\",\"idType\":\"SLUG\"}",25],["{\"id\":\"gutenberg-in-headless-wordpress-wpgraphql-gutenberg\",\"idType\":\"SLUG\"}",26],["{\"first\":12,\"after\":\"YXJyYXljb25uZWN0aW9uOjI1MQ==\"}",27],["{\"id\":\"building-an-e-commerce-site-using-shopify-headless-wordpress-nextjs-and-chakra-ui-part-1-setup\",\"idType\":\"SLUG\"}",28],["{\"id\":\"what-is-headless\",\"idType\":\"SLUG\"}",29],["{\"id\":\"headless-wordpress-with-vue-and-nuxt-js\",\"idType\":\"SLUG\"}",30],["{\"id\":\"graphql-code-generator-for-wpgraphql\",\"idType\":\"SLUG\"}",31],["{\"id\":\"previews-in-headless-wordpress-using-nextjs\",\"idType\":\"SLUG\"}",32],["{\"id\":\"set-up-wordpress-as-a-headless-cms\",\"idType\":\"SLUG\"}",33],["{\"id\":\"wp-login.php\",\"idType\":\"SLUG\"}",34],["{\"id\":\"introduction-to-graphql-in-wordpress\",\"idType\":\"SLUG\"}",35],["{\"id\":\"introduction-to-the-wordpress-rest-api\",\"idType\":\"SLUG\"}",36],["{\"id\":\"custom-content-types-in-headless-wordpress\",\"idType\":\"SLUG\"}",37],["{\"first\":12,\"after\":\"null\"}",38],["{\"first\":12,\"after\":\"undefined\"}",39],["{\"id\":\"state-of-headless-development\",\"idType\":\"SLUG\"}",40],["{\"id\":\"sitemap.xml\",\"idType\":\"SLUG\"}",41],["{\"id\":\"what-is-atlas-content-modeler“javascript:alert(document.lastModified)”\",\"idType\":\"SLUG\"}",42],["{\"id\":\"...\",\"idType\":\"SLUG\"}",43],["{\"id\":\"apollo-client-cache-rehydration-in-next-js.highlight\",\"idType\":\"SLUG\"}",44]],[[0,4],[3,1],[5,0],[8,0],[10,23],[13,0],[14,0]],"v0"]}

Define “render”…

Where?

When?

The future of rendering

Hybrid rendering

Build time

It’s SSG! It’s SSR! No, it’s ISR/DSG/DPR, aka “the new hotness”!

Next

Gatsby

Conclusion

What We’ll Build

Pages

Content Models

Provider

Location

Create Content Models

Location Model

Location Model Fields

Location Model Query

Provider Model

Provider Model Fields

Specialty Taxonomy

Provider Model Query

Next.js App Walkthrough

Providers Page

Side-Note on Bi-Directional Relationship Queries

Summary

How Can I Help?

How WPGraphQL Gutenberg Works

Setup

WordPress Backend Setup

Next.js App Setup

Render Blocks

Fix Internal Links

Custom Server-side Block Parser

Convert Anchor tags to Link Components

Other Uses

Style Blocks

Trade-off: Control vs. Ease of Implementation

Wrapping Up

Render Gutenberg Blocks as HTML

Fix Internal Links for Headless Gutenberg

Style Blocks

Use a Parser to Convert Some Blocks to Components

Example: Convert Anchor tags to Link Components

Other Uses

Trade-off: Control vs. Ease of Implementation

Wrapping Up

Introducing Atlas Content Modeler

Content Modeler Real-World Usage

Local Setup

Project Model Creation

Custom Fields

Working with the Model in the WordPress Admin

Query for Data via WPGraphQL

Next.js App Example

Where to Go from Here?

How Can I Help?

Getting Started

WordPress Backend Setup

Next.js App Setup

Try it Out!

How it Works

A Note on Security

Apollo Client Configuration

useAuth() Hook

AuthContent & UnAuthContent Components

AuthContent

UnAuthContent

Features

Nav

Log In

Log Out

New User Sign-up

Set Password Link

Set Password Form

Password Strength Validation

Password Resets

User Profile Page

Members Page

`useAuth()` Hook