{"cache":{"posts1":{"__typename":"RootQueryToPostConnection","nodes":[{"__typename":"Post","id":"cG9zdDozODE=","uri":"/rendering-patterns-in-headless-wordpress/","seo":{"__typename":"PostTypeSEO","readingTime":9,"title":"Rendering Patterns in Headless WordPress - Headless WordPress Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMw==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/052087cdcfcc56801a256bec6c66fb1c?s=96&d=mm&r=g"},"name":"Theo Despoudis","description":"---\r\ntitle: Sr. Software Engineer\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"title0":"Rendering Patterns in Headless WordPress","slug":"rendering-patterns-in-headless-wordpress","excerpt0":"

\n","content0":"\n

One of the most common pain points among developers is understanding the possible ways to render content when it comes to Headless WordPress. Those are the three letter acronyms that you might hear or read like SSG, CSR, SSR etc. in conversations and the like. If you find yourself reading about them and don’t still don’t really understand what they represent or how they affect the user experience or performance, you might not be optimizing your site as well as you could be.

\n\n\n\n

To provide insight into that topic, this tutorial explains the four key rendering patterns in headless WordPress. We start by describing what the patterns are, then we provide practical examples of utilizing them using Faust.js which is the headless WordPress Framework for React.

\n\n\n\n

Let’s get started.

\n\n\n\n

Server Side Rendering (SSR)

\n\n\n\n

In a traditional WordPress installation, when a user visits a site, the server will construct a full HTML response and send it back to the user’s browser. The nature of this request-response cycle is dynamic; the PHP server that powers WordPress will connect to the database to fetch the latest blog posts, it will determine which template to use based on the visited page, run any filters and callbacks and respond with the full HTML string.

\n\n\n\n

Visiting the same page multiple times does not mean you will get the same results every time. However, because you receive the full content of the page, search engines like Google can crawl it easier and faster. This is what Server Side Rendering or SSR is all about.

\n\n\n\n

Most traditional Web 1.0 and 2.0 applications including WordPress use Server Side Rendering for delivering dynamic content. SSR offers a reasonable balance of flexibility, simplicity and performance.

\n\n\n\n

Faust.js fully supports Next.js SSR. This is achieved by exporting an async function called getServerSideProps (see docs), which will be called by the server on each request, and wrap it in getNextServerSideProps:

\n\n\n\n

// File ssr.js\nimport { client } from 'client';\nimport { GetServerSidePropsContext } from 'next';\nimport { getNextServerSideProps } from '@faustjs/next';\n\nexport default function Page() {\n  const { usePosts } = client;\n  return (\n    <>\n      <main className=\"content content-single\">\n        <div className=\"wrap\">\n          <h2>Recent Posts</h2>\n          {usePosts()?.nodes.map((post) => (\n            <li key={post.id}>{post.title()}</li>\n          ))}\n        </div>\n      </main>\n    </>\n  );\n}\n\nexport async function getServerSideProps(context) {\n  return getNextServerSideProps(context, {\n    Page: Page,\n    client,\n  });\n}\n

\n\n\n\n

Note that in this case, the server needs to request data from WordPress using a GraphQL request. For that to happen, we need to pass the Page and the client as parameters to getNextServerSideProps. This way is specific to Faust.js and it uses the client perform the request to fetch the posts behind the scenes without having to think about batching/constructing queries, or data fetching.

\n\n\n\n

If you inspect the response from the server, you will notice that the whole HTML string is returned showing the list of recent posts:

\n\n\n\n

\n\n\n\n

If you go back and change the title of one of the post what do you think will happen? Well the new change back to the response as the server will always request the updated content:

\n\n\n\n

\n\n\n\n

However, SSR is not without tradeoffs. Notice that by default, without any optimizations or caching, the server has to do a lot of work. When the request reaches the server via the WPGraphQL endpoint it has to connect to the database. It has to gather all the data from possibly multiple database tables and has to generate the whole HTML string. SSR does not scale well when many users are hitting the website. The server has to consume a lot of memory and bandwidth to perform well consistently. There are well-known mitigation techniques to reduce the chance of hitting the server like HTTP cache control headers, object caching or HTTP cache proxies but those are still not perfect solutions.

\n\n\n\n

We explore some additional rendering patterns that are available to headless WordPress technologies that help improve the speed of serving content at scale.

\n\n\n\n

Client Side Rendering (CSR)

\n\n\n\n

If Server Side Rendering offloads the rendering effort to the server, Client Side Rendering (CSR) on the other hand places this responsibility on the client.

\n\n\n\n

When you visit a page that does Client Side Rendering you won’t get back a full HTML document. Instead, you will have a bare skeleton component, and client-side JavaScript will be responsible for populating it with content. “Client” here refers to the web browser, such as Chrome, Firefox or Safari. This is how many Single Page Applications (SPAs) work.

\n\n\n\n

In order to turn our component into CSR using Faust we will have to work a bit harder. We will need to move all the fetching of the Posts inside the component and remove the getServerSideProps. This is because by default Next.js performs automatic static optimization and pre-render the pages even if you didn’t specify any props:

\n\n\n\n

// csr.js\nimport { useEffect, useState } from \"react\";\nimport { client } from 'client';\nimport { prepass, getArrayFields } from \"gqty\";\n\n\nfunction Page() {\n  const [posts, setPosts] = useState([]);\n  useEffect(() => {\n    const fetchPosts = async () => {\n      const {\n        client: {resolved, query},\n      } = client;\n\n      resolved(() => {\n        return query.posts();\n      }, {refetch: true}).then(res => {\n        prepass(res?.nodes, 'id', 'title', '__typename');\n        setPosts(getArrayFields(res?.nodes, 'id', 'title', '__typename'))\n      })\n    }\n    fetchPosts();\n  }, []);\n\n  return (\n    <>\n      <main className=\"content content-single\">\n        <div className=\"wrap\">\n          <h2>Recent Posts</h2>\n          {posts?.map((post) => (\n            <li key={post.id ?? ''}>{post.title()}</li>\n          ))}\n        </div>\n      </main>\n    </>\n  );\n}\n\nexport default Page;\n

\n\n\n\n

It uses the useEffect() hook to perform the request on the client side. The resolved method from the GQty client performs a GraphQL request and returns a promise object. It sets the state once the data is fetched from the WordPress instance and uses prepass and getArrayFields function helpers to force resolving the specified properties of the post values from the list and return a Value object instead of a Proxy object.

\n\n\n\n

Once you have visited a page that does CSR and inspect the initial HTML you will see that it renders only the heading:

\n\n\n\n

\n\n\n\n

Then you will notice that the page will load the posts in a quick succession. This is because there is a GraphQL request pending in the background:

\n\n\n\n

\"\" — Client side GraphQL request to fetch the posts

\n\n\n\n

This prolonged initial load time makes CSR decreases the overall user experience. Many designers use loading indicators, skeleton components or prefetching to mitigate this side effect.

\n\n\n\n

Additionally because the initial Page is rendered without meaningful content the SEO score will take a hit as the crawler robot has to be able to run JavaScript to evaluate the whole page.

\n\n\n\n

However the benefits of CSR is that after the initial load, the page becomes more snappy and you have almost instant transitions as the pages are rendered within the client.

\n\n\n\n

We next explore how Static Site Generation (SSG) works.

\n\n\n\n

Static Site Generation (SSG)

\n\n\n\n

Both SSR and CSR are responsible for delivering dynamic content. Their main difference is when the request happens and which component is responsible for rendering the response. What about pages that do not need to change and could benefit from building them once and serve using a CDN?

\n\n\n\n

This is what Static Side Generation (SSG) does essentially. It collects all the static pages ahead of time creates static HTML files for each one of them. When a user visits a page, the server will just serve the file as it is. No dynamic requests happening there.

\n\n\n\n

Faust.js leverages Next.js Automatic Static Site Generation. By default when you run the production build via npm run build it will create static pages for your pages whenever possible:

\n\n\n\n

\n\n\n\n

Each page generated will be served by the Next.js server which means that you still need an application server to run these. You also have the option to generate truly static HTML files when running the npm run export command.

\n\n\n\n

\n\n\n\n

SSG pages are served very fast, are very secure , it does not penalise their SEO score and you can leverage CDNs to literally host them for free.

\n\n\n\n

However their main caveat is that the more pages it creates, the longer it takes to rebuild the whole site. If you have a WordPress site that does not change very often, it pays off to just statically export it into a Headless site and serve it with unlimited bandwidth and ultra fast speed without incurring any extra costs other than the WordPress hosting.

\n\n\n\n

Incremental Static Regeneration (ISR)

\n\n\n\n

Incremental Static Regeneration (ISR is a hybrid approach between SSG pages (serving static content) and SSR pages (serving dynamic content). It takes the ideas of those rendering patterns and tries to combine them together.

\n\n\n\n

The way it works is like this:

\n\n\n\n

It builds pages using SSG.
It adds a timer to revalidated certain pre-build pages instead of re-building the whole site.
Once a timer is elapsed, then the next visit to that page will trigger a re-build for that page. The user will be served with an updated content just like SSR. The difference is that it will only revalidate after a certain amount of time.

\n\n\n\n

With Faust.js you get automatic ISR support whenever you use the getNextStaticProps function:

\n\n\n\n

export async function getStaticProps(context: GetStaticPropsContext) {\n  return getNextStaticProps(context, {\n    Page: MyPage,\n    // Next.js will attempt to re-generate the page:\n    // - When a request comes in\n    // - At most once every 900 seconds\n    client,\n  });\n}

\n\n\n\n

By default it sets the timer for 900 seconds (15 minute) and when a request comes in at most once during that time it will be served with an updated content. If you want to test it quickly yourself, try using a smaller value like 10 seconds and try to update a post in the WP Admin. You will see that when visiting the page after that 10 seconds have passed, you will see the new changes.

\n\n\n\n

ISR is great if you want to be able to update content on a website but still enjoy the benefits of SSG. However it’s not great if you want your users to view updated data all the time without any delays.

\n\n\n\n

Conclusion

\n\n\n\n

Headless WordPress technologies allow for many rendering patterns each with different pros and cons. With Faust.js, developers can adopt a trusted framework for developing extremely flexible and scalable headless sites powered by WordPress. This article serves as a reference point regarding headless WordPress rendering patterns. Thanks for reading!

\n"},{"__typename":"Post","id":"cG9zdDo0Mzg=","uri":"/build-a-simple-headless-wordpress-app-with-react-wpgraphql/","seo":{"__typename":"PostTypeSEO","readingTime":14,"title":"Crash Course: Build a Simple Headless WordPress App with React & WPGraphQL - Headless WordPress Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMQ==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/8ee8d4ed6d4b3a916be500eb1bcf03f4?s=96&d=mm&r=g"},"name":"Grace Erixon","description":"---\r\ntitle: Associate Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"title0":"Crash Course: Build a Simple Headless WordPress App with React & WPGraphQL","slug":"build-a-simple-headless-wordpress-app-with-react-wpgraphql","excerpt0":"

In this tutorial, you will learn how to create a simple headless WordPress app using React and WPGraphQL. This tutorial assumes a basic understanding of JavaScript, React fundamentals, GraphQL fundamentals, and WordPress. Using the prepared Code Sandbox repository will allow us to focus on points specific to React as a framework and Apollo Client for […]

\n","content0":"\n

\n\n\n\n

Use the GraphiQL IDE to compose GraphQL queries
Use Apollo Client to fetch data in your app and render it to the page
Use variables in GraphQL queries

\n\n\n\n

Code Sandbox Overview

\n\n\n\n

First, let’s open up the Code Sandbox that we have prepared for this project. Here’s the link!

\n\n\n\n

If you haven’t used Code Sandbox previously, there are four sections on the screen. On the left, you can see the file structure of your project. Below are the dependencies that we’ve already added to this project (@apollo/client & graphql). You can make changes to the files using the code editor in the middle and see your changes reflected in real-time in the embedded browser on the right.

\n\n\n\n

\n\n\n\n

If at any point you encounter an unexpected error after you make changes, you can refresh the embedded browser, or even refresh the whole Code Sandbox page to get things working again. CodeSandbox will have saved your changes.

\n\n\n\n

React App Overview

\n\n\n\n

Before we start coding, let’s take a look at the current state of this Code Sandbox application. In the embedded browser, it is displaying a page titled Blog that consists of many cards. Each card contains data for a blog post, including the post’s title, date, author, and featured image, if it has one.

\n\n\n\n

\n\n\n\n

We can also click on each of these cards to view an individual post details page. This page includes much of the same information as on the card, and also contains the post’s content. In the address bar of the embedded browser, we can also see that the URL changes to reflect the current page.

\n\n\n\n

\n\n\n\n

How are we making this happen? Open the App.js file in the Code Sandbox project. In this file, we are first importing React and some packages from react-router-dom to handle our routing. Then, we’re importing two files – HomePage and PostPage – as well as some styles for our app.

\n\n\n\n

Inside of the <Switch> tag, the two <Route> tags are managing the routing. They check the path from the browser and render a certain component based on that path. As you change the URL while navigating the site, the component being displayed changes. This forms the basis of our navigation between the HomePage showing the list of all posts and the PostPage showing the individual post’s details.

\n\n\n\n

Now, let’s dive deeper into the HomePage. /pages/HomePage.js looks like this:

\n\n\n\n

export default function HomePage() {\n  return (\n    <div className=\"page-container\">\n      <h1>Blog</h1>\n      <PostsList />\n    </div>\n  );\n}

\n\n\n\n

HomePage renders a component called PostsList, which lives in /components/PostsList.js and looks like this:

\n\n\n\n

import React from \"react\";\nimport PostCard from \"../components/PostCard\";\nimport { data } from \"../dummy-data/posts\";\n\nexport default function PostsList() {\n  const loading = false;\n  const error = null;\n\n  if (loading) return <p>Loading posts...</p>;\n  if (error) return <p>Error :(</p>;\n\n  const postsFound = Boolean(data?.posts.nodes.length);\n  if (!postsFound) {\n    return <p>No matching posts found.</p>;\n  }\n\n  return (\n    <div className=\"posts-list\">\n      {data.posts.nodes.map((post) => (\n        <PostCard key={post.databaseId} post={post} />\n      ))}\n    </div>\n  );\n}

\n\n\n\n

This is where the actual data fetching occurs to display the list of all posts on the HomePage. However, we are currently importing hard-coded JSON dummy data from the /dummy-data/posts.js file to populate this page. Your challenge is to remove this dummy data and fetch REAL data from a headless WordPress backend. This is where WPGraphQL and Apollo Client come in!

\n\n\n\n

Create an Apollo Client Instance

\n\n\n\n

Let’s get started with setting up our React app to fetch data from a WordPress backend! A number of GraphQL clients exist that you could use for this purpose. For our app, we’re going to use Apollo Client. Per Apollo Client’s Get Started documentation, we first need to create an instance of Apollo Client.

\n\n\n\n

Inside the src directory, create a new folder called lib. Inside lib, create a file named apollo.js. Inside the newly created /lib/apollo.js file, add the following code:

\n\n\n\n

import { ApolloClient, InMemoryCache } from \"@apollo/client\";\n\nconst client = new ApolloClient({\n  uri: ' ',\n  cache: new InMemoryCache(),\n});\n\nexport default client;

\n\n\n\n

The first line of code here imports ApolloClient and InMemoryCache from the @apollo/client package. Then, below that, we create a new instance of ApolloClient and export that as a variable named client. When we create the new client, we pass in a configuration object with uri and cache properties.

\n\n\n\n

The cache property gets assigned to a new InMemoryCache instance. With this in place, the cache will “remember” the results of the GraphQL queries that get executed. If the same queries are requested again, Apollo Client will resolve the requests using the data in its cache rather than making a new network request every time. Read more about Apollo Client’s caching capabilities here.

\n\n\n\n

The uri property needs to point to the GraphQL endpoint we want to source our data from. The endpoint that we will be using for this tutorial is https://content.wpgraphql.com/graphql. If you already have a WordPress server with an instance of WPGraphQL installed, you can use that instead, if you’d like. After adding this value to the uri, our file will look like this:

\n\n\n\n

import { ApolloClient, InMemoryCache } from \"@apollo/client\";\n\nconst client = new ApolloClient({\n  uri: 'https://content.wpgraphql.com/graphql',\n  cache: new InMemoryCache(),\n});\n\nexport default client;

\n\n\n\n

With our client fully configured, the next step is to make it available anywhere in our application using the ApolloProvider component.

\n\n\n\n

Implement Apollo Provider Component

\n\n\n\n

Apollo Client provides an ApolloProvider component that can be used to add the ApolloClient instance we created to React context. This will allow us to run GraphQL queries from anywhere within our app’s component tree.

\n\n\n\n

Inside of App.js, add the following import statements. These pull in the client we created in the previous step and the ApolloProvider component that Apollo Client provides. We will need both of these to make a connection.

\n\n\n\n

import { ApolloProvider } from \"@apollo/client/react\";\nimport client from \"../lib/apollo\";

\n\n\n\n

Next, wrap the <Switch> component inside of an <ApolloProvider> component, passing the configured client as a prop:

\n\n\n\n

export default function App() {\n  return (\n    <ApolloProvider client={client}>\n      <Switch>\n        <Route exact path=\"/\" component={HomePage} />\n        <Route path=\"/blog/:slug\" component={PostPage} />\n      </Switch>\n    </ApolloProvider>\n  );\n }

\n\n\n\n

Wrapping your app in an ApolloProvider gives you the ability to use the React hooks that Apollo Client provides, such as useQuery(), from anywhere in your app.

\n\n\n\n

Import `useQuery()` Hook in `PostsList`

\n\n\n\n

Now that we have a fully configured GraphQL client, we can start fetching some real data inside of our components. As mentioned previously, the HomePage component inside /pages/HomePage.js renders the PostsList component to display the list of blog posts. Open up /components/PostsList.js in the editor so we can take a look at the PostsList component.

\n\n\n\n

export default function PostsList() {\n const loading = false;\n const error = null;\n\n if (loading) return <p>Loading posts…</p>;\n if (error) return <p>Error :(</p>;\n\n const postsFound = Boolean(data?.posts.nodes.length);\n if (!postsFound) {\n   return <p>No matching posts found.</p>;\n }\n\n return (\n   <div className=\"posts-list\">\n     {data.posts.nodes.map((post) => (\n       <PostCard key={post.databaseId} post={post} />\n     ))}\n   </div>\n );\n}

\n\n\n\n

This PostsList component first includes checks for whether the data is loading, returned an error, or is empty. If none of these conditions are true, then the code maps over the array of data, passing rendering a PostCard component for each.

\n\n\n\n

For now, this component is pulling in placeholder dummy data. Let’s work toward populating it with dynamic data. First, let’s import two things – gql and useQuery – at the top of our /components/PostsList.js file:

\n\n\n\n

import { gql, useQuery } from \"@apollo/client\";

\n\n\n\n

So now we’re set up to fetch data, but what does our GraphQL query need to look like? 🤔 Let’s learn how to compose the GraphQL query we need using the GraphiQL IDE, next.

\n\n\n\n

Compose GraphQL Query Using the GraphiQL IDE

\n\n\n\n

To compose our GraphQL query, we’ll use a hosted instance of the GraphiQL IDE that’s available at graphiql-online.com. (Note the “i” in “GraphiQL”! It can easily be mistaken for the word “GraphQL” at first glance 😊).

\n\n\n\n

Once you’ve opened graphiql-online.com in a new browser tab, enter https://content.wpgraphql.com/graphql for the GraphQL endpoint and click the button to continue. Recall that this is the same endpoint that we configured Apollo Client to use inside of /lib/apollo.js.

\n\n\n\n

All of the data that exists in the GraphQL schema is shown in the Explorer section on the left. Developers can select boxes to indicate which data they would like to fetch, then GraphQL builds the query for them! Give it a try! Once you’ve checked a few boxes and composed a query, hit the play icon (▶️) to execute it and see the data that gets returned in the right-most pane.

\n\n\n\n

By looking at the data inside of /dummy-data/posts.js, we can see the shape of the data that our PostsList component expects. Using the GraphiQL Explorer, try to compose a query that looks like this:

\n\n\n\n

\n\n\n\n

Once you compose a query that’s returning the correct data, we can copy/paste that query into our app.

\n\n\n\n

Format Query with `gql`

\n\n\n\n

Back in the PostsList component, add this code underneath the import statements. Here, we pass the query we composed to a gql tagged template literal (“gql” followed by two backticks) and assign the return value to a GET_ALL_POSTS variable.

\n\n\n\n

const GET_ALL_POSTS = gql`\n  query getAllPosts {\n    posts {\n      nodes {\n        databaseId\n        title\n        slug\n        author {\n          node {\n            name\n          }\n        }\n        featuredImage {\n          node {\n            altText\n            sourceUrl\n          }\n        }\n      }\n    }\n  }\n`;

\n\n\n\n

gql takes care of converting the query string into an abstract syntax tree (AST) object that Apollo Client can work with.

\n\n\n\n

Fetch Data with the `useQuery()` Hook

\n\n\n\n

Now let’s actually execute our GraphQL query. First, delete the dummy data import statement:

\n\n\n\n

import { data } from \"../dummy-data/posts\";

\n\n\n\n

…and also delete these variables from inside of the export statement in the PostsList component:

\n\n\n\n

const loading = false;\nconst error = null;

\n\n\n\n

We will replace those variables with the destructed response that we get from useQuery(). Passing the GET_ALL_POSTS function into useQuery() will result in values for variables named loading, error, and data:

\n\n\n\n

const { loading, error, data } = useQuery(GET_ALL_POSTS);

\n\n\n\n

Finally, our HomePage is dynamic! You should now be able to hit the refresh button on the embedded browser and see the “Loading posts…” message momentarily, then see the grid of posts appear.

\n\n\n\n

Congratulations! You are now successfully pulling data from a headless WordPress backend and rendering it out inside of a React app! 🎉

\n\n\n\n

The final PostsList.js file should look like this:

\n\n\n\n

import React from \"react\";\nimport PostCard from \"../components/PostCard\";\nimport { gql, useQuery } from \"@apollo/client\";\n\nconst GET_ALL_POSTS = gql`\n  query getAllPosts {\n    posts {\n      nodes {\n        databaseId\n        title\n        slug\n        author {\n          node {\n            name\n          }\n        }\n        featuredImage {\n          node {\n            altText\n            sourceUrl\n          }\n        }\n      }\n    }\n  }\n`;\n\nexport default function PostsList() {\n const { loading, error, data } = useQuery(GET_ALL_POSTS);\n\n if (loading) return <p>Loading posts…</p>;\n if (error) return <p>Error :(</p>;\n\n const postsFound = Boolean(data?.posts.nodes.length);\n if (!postsFound) {\n   return <p>No matching posts found.</p>;\n }\n\n return (\n   <div className=\"posts-list\">\n     {data.posts.nodes.map((post) => (\n       <PostCard key={post.databaseId} post={post} />\n     ))}\n   </div>\n );\n}

\n\n\n\n

In the next section, we’ll look at making similar changes to the PostPage file.

\n\n\n\n

Making `PostPage.js` Dynamic

\n\n\n\n

In the last section, we focused on pulling multiple posts into the site home page using Apollo Client and WPGraphQL. This section will build on that example and look at how to create individual pages for each blog post, each with a unique URL.

\n\n\n\n

To begin, let’s open the /pages/PostPage.js file and look at the existing code. It currently imports dummy data from /dummy-data/post.js and passes it into the PostPageContent component.

\n\n\n\n

import React from \"react\";\nimport { Link } from \"react-router-dom\";\nimport PostPageContent from \"../components/PostPageContent\";\nimport { data } from \"../dummy-data/post\";\n\nexport default function PostPage(props) {\n  const loading = false;\n  const error = null;\n  const postFound = true;\n\n  return (\n    <div className=\"page-container\">\n      <Link to=\"/\">← Home</Link>\n      {loading ? (\n        <p>Loading...</p>\n      ) : error ? (\n        <p>Error: {error.message}</p>\n      ) : !postFound ? (\n        <p>Post could not be found.</p>\n      ) : (\n        <PostPageContent post={data.post} />\n      )}\n    </div>\n  );\n}

\n\n\n\n

As we did once before, let’s remove the dummy data and do some real data fetching instead.

\n\n\n\n

Construct `GET_POST_BY_SLUG` Query

\n\n\n\n

Back in the GraphiQL IDE, use the Explorer once more and select post from the list of schema objects. If you check the id and idType options, GraphiQL will help you begin to parameterize your query so that we can pass in variables. First, we can set the idType to SLUG from the dropdown in the Explorer. We want to use a dynamic variable for the slug so it can change every time we hit a new route. To accomplish this, we’ll have the query accept a $id variable with a required type of ID, like this: getPostBySlug($id: ID!). Next, we’ll pass that value in as the id, like this: post( id: $id, idType: SLUG ). This tells GraphQL to use the value of $id to locate the blog post.

\n\n\n\n

Your query should then look like the one shown below. You can once again hit the play icon (▶️) to execute it and see the data that gets returned in the right-most pane.

\n\n\n\n

\n\n\n\n

As you can see, this query returned an error because there was no id value specified. We can fix this by passing in the slug from one of the posts that our getAllPosts query returned previously in the Query Variables pane at the bottom of the screen, like this:

\n\n\n\n

{\n  \"id\": \"query-any-page-by-its-path-using-wpgraphql\"\n}

\n\n\n\n

Now, if we press the play icon (▶️) again, the query should return the corresponding post details.

\n\n\n\n

\n\n\n\n

Once you verify that the query is correct, we will copy/paste the query that you composed into your app.

\n\n\n\n

Call `useQuery()` Hook from `PostPage.js`

\n\n\n\n

Now let’s execute our GraphQL query. Back in the /pages/PostPage.js file, delete the dummy data import statement:

\n\n\n\n

import { data } from \"../dummy-data/post\";

\n\n\n\n

Then, let’s import two things: gql and useQuery:

\n\n\n\n

import { gql, useQuery } from \"@apollo/client\";

\n\n\n\n

Next, add this code underneath the import statements. Here, we once again will pass the query we composed to gql and assign the return value to a GET_POST_BY_SLUG variable.

\n\n\n\n

const GET_POST_BY_SLUG = gql`\n  query getPostBySlug($id: ID!) {\n    post(id: $id, idType: SLUG) {\n      title\n      date\n      content\n      categories {\n        nodes {\n          slug\n          name\n        }\n      }\n      author {\n        node {\n          name\n        }\n      }\n    }\n  }\n`;

\n\n\n\n

Now that our query is set up in the application, we can use it throughout the rest of this page component.

\n\n\n\n

First, inside of the export statement in the PostPage component, delete these two lines:

\n\n\n\n

const loading = false;\nconst error = null;

\n\n\n\n

We will replace those variables with the destructed response that we get from useQuery(). Passing the GET_POST_BY_SLUG function into useQuery() will result in values for variables named loading, error, and data:

\n\n\n\n

const { loading, error, data } = useQuery(GET_POST_BY_SLUG);

\n\n\n\n

However, we need to pass the slug into our useQuery() hook as a parameter. We can access the slug through the props value that is passed into the PostPage component at props.match.params.slug and send it through useQuery() as a specifically-formatted object. We can edit the code from the previous step to include this:

\n\n\n\n

const { loading, error, data } = useQuery(GET_POST_BY_SLUG, {\n\tvariables: {\n\t\tslug: props.match.params.slug\n\t}\n}\n

\n\n\n\n

Lastly, we also need to replace the postFound variable with a Boolean value indicating whether or not there is a post present inside of data.

\n\n\n\n

const postFound = Boolean(data?.post);

\n\n\n\n

After making these changes, our final /pages/PostsPage.js file should look like this:

\n\n\n\n

import React from \"react\";\nimport { Link } from \"react-router-dom\";\nimport PostPageContent from \"../components/PostPageContent\";\nimport { gql, useQuery } from \"@apollo/client\";\n\nconst GET_POST_BY_SLUG = gql`\n  query getPostBySlug($id: ID!) {\n    post(id: $id, idType: SLUG) {\n      title\n      date\n      content\n      categories {\n        nodes {\n          slug\n          name\n        }\n      }\n      author {\n        node {\n          name\n        }\n      }\n    }\n  }\n`;\n\nexport default function PostPage(props) {\n const { loading, error, data } = useQuery(GET_POST_BY_SLUG, {\n\tvariables: {\n\t\tslug: props.match.params.slug\n\t}\n}\n\n const postFound = Boolean(data?.post);\n\n return (\n   <div className=\"page-container\">\n     <Link to=\"/\">← Home</Link>\n     {loading ? (\n       <p>Loading…</p>\n     ) : error ? (\n       <p>Error: {error.message}</p>\n     ) : !postFound ? (\n       <p>Post could not be found.</p>\n     ) : (\n       <PostPageContent post={data.post} />\n     )}\n   </div>\n );\n}

\n\n\n\n

Done! 🎉

\n\n\n\n

You should now be able to navigate back and forth between the homepage, which shows the list of posts, and the single post pages.

\n\n\n\n

Congratulations on creating a headless WordPress site! Thanks to your hard work, the app is now leveraging Apollo Client and WPGraphQL to pull data from a real headless WordPress backend and use it to render your pages!

\n\n\n\n

We covered a lot of ground in this crash course. Hopefully, you now have a good understanding of how you can leverage tools like React and WPGraphQL to build headless WordPress sites.

\n\n\n\n

Thanks for following along!

\n"},{"__typename":"Post","id":"cG9zdDozOTQ=","uri":"/crash-course-build-a-simple-headless-wordpress-app-with-next-js-wpgraphql/","seo":{"__typename":"PostTypeSEO","readingTime":19,"title":"Crash Course: Build a Simple Headless WordPress App with Next.js & WPGraphQL - Headless WordPress Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMg==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/a64abda82041a00e479ecc2b156d7947?s=96&d=mm&r=g"},"name":"Jeff Everhart","description":"---\r\ntitle: Sr. Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"title0":"Crash Course: Build a Simple Headless WordPress App with Next.js & WPGraphQL","slug":"crash-course-build-a-simple-headless-wordpress-app-with-next-js-wpgraphql","excerpt0":"

In this tutorial, you will learn how to create a simple headless WordPress app using Next.js and WPGraphQL. This tutorial assumes a basic understanding of JavaScript, React, and WordPress. Using the prepared GitHub repository will allow us to focus on points specific to Next.js as a framework and Apollo Client for data fetching in WPGraphQL. […]

\n","content0":"\n

\n\n\n\n

Create static and dynamic routes in Next.js
Use the GraphiQL IDE to compose GraphQL queries
Use Apollo Client fetch data in your app
Choose appropriate Next.js rendering methods based on your content

\n\n\n\n

Prerequisites

\n\n\n\n

To get started, you’ll need to make sure that you have both Node.js and npm installed. If you aren’t sure whether or not you have this software installed, you can run the following commands in your terminal:

\n\n\n\n

node -v\nnpm -v

\n\n\n\n

The terminal output should either tell you which versions you have installed or that it cannot find the commands node or npm to run them. Using a tool like nvm (Node Version Manager) to install and manage versions of Node.js on your machine can be helpful when working on multiple projects.

\n\n\n\n

Configure Your WordPress Site

\n\n\n\n

Next, let’s set up a local WordPress site that can be used as the data source for our example application. In the next section, we will walk through creating a WordPress site via Local and populating that with some test data. If you already have a WordPress site that you want to use, you can skip ahead to the “Install Plugins and Check Settings” section.

\n\n\n\n

Create a WordPress Site with Local

\n\n\n\n

Local is WP Engine’s local development tool, and it makes it very easy to work with WordPress locally. You can install the app and create a new WordPress site in a few steps.

\n\n\n\n

Click Create A New Site on the application home screen to create a new site.

\n\n\n\n

\n\n\n\n

Choose a name for your new site, and then click Continue.

\n\n\n\n

\n\n\n\n

For most users, you can stick with the Preferred installation environment, and then click Continue.

\n\n\n\n

\n\n\n\n

Lastly, specify values for the WordPress Username and WordPress Password, and be sure to remember these values. Once that is complete, click Add Site.

\n\n\n\n

\n\n\n\n

Depending on your permissions, Local may ask for permission to make modifications to your system. After your site has been successfully installed, you will see it in the Local dashboard.

\n\n\n\n

\n\n\n\n

To access the WP Admin panel of your new site, click Admin in the site details pane. You will need to authenticate with the username and password you created in the previous step.

\n\n\n\n

Install Plugins and Check Settings

\n\n\n\n

With a basic WordPress site up and running, there are a few things left to install and some settings to check.

\n\n\n\n

Check Permalink Settings

\n\n\n\n

All of the code in this crash course assumes that you have the Post name option selected for your permalink settings. To check or modify this setting, open the Settings > Permalinks menu in the WP Admin dashboard.

\n\n\n\n

\n\n\n\n

Install WPGraphQL and Enable Debug Mode

\n\n\n\n

From the Plugins > Add new menu, search for wpgraphql in the WordPress plugin repository. Install and activate the plugin, which will add a GraphQL tab to your WP Admin sidebar.

\n\n\n\n

\n\n\n\n

Activate Debug Mode. Open the GraphQL > Settings menu and check the option labeled Enable GraphQL Debug Mode and then click Save Changes.

\n\n\n\n

\n\n\n\n

With Debug Mode enabled, you will get more helpful error output as your develop your application. Note that using Debug Mode is not recommended for production sites.

\n\n\n\n

Import Placeholder Content

\n\n\n\n

If you’re working with a newly created WordPress site, you can run the import process on this export file to create some placeholder content for use with this tutorial.

\n\n\n\n

Get Your Next.js App Running Locally

\n\n\n\n

Now that you have a WordPress site with at least some content, whether running locally or on the web, we can get started with Next.js.

\n\n\n\n

The rest of this tutorial is based on the files that can be found in the crash course’s GitHub repository. This repository is heavily based on the default Next.js template created with create-next-app CLI tool, with some additional scaffolding and styles provided by the WP Engine DevRel team.

\n\n\n\n

To clone the repository to you local machine, you can run the following command:

\n\n\n\n

git clone https://github.com/JEverhart383/crash-course-headless-wp-next-wpgraphql.git

\n\n\n\n

Once the project finishes cloning, run the following commands to switch into that directory and install all of the project’s dependencies using npm. After the dependencies finish downloading, you can run the project in your browser using npm run dev.

\n\n\n\n

cd crash-course-headless-wp-next-wpgraphql\nnpm install\nnpm run dev

\n\n\n\n

With the app running locally, you should be able to view the app at http://localhost:3000 in your browser, and the app will recompile and update as make changes to the files in the project directory.

\n\n\n\n

All of the posts you see on the local site are dummy data sourced from a local JSON file. In the next step, we’ll connect Apollo Client to WordPress and WPGraphQL to display actual post data from your site.

\n\n\n\n

Connect Apollo Client to WordPress

\n\n\n\n

The first step in replacing our mock post data with data from your WordPress site involves configuring Apollo Client to work with your site via WPGraphQL.

\n\n\n\n

While technically, you could POST your queries directly to your GraphQL server using only the Fetch API, using a GraphQL client like Apollo Client has a lot of added benefits that are beyond the scope of this post. Many of the following steps are also contained on the Get Started page of the Apollo Client docs, so be sure to reference that page if you are interested in learning more about the library.

\n\n\n\n

Create a .env File

\n\n\n\n

The first thing we’ll do to start this process is make the URL of our WordPress site available to our application through an environment variable. By default, Next.js will look for a file named .env.local in the root directory of the project to load any environment variables.

\n\n\n\n

Create a file named .env.local in the project’s root directory.

\n\n\n\n

Open the file and paste in the following line, replacing “https://headlesswp.local” with the URL of your WordPress site.

\n\n\n\n

NEXT_PUBLIC_WORDPRESS_API_URL=https://headlesswp.local

\n\n\n\n

By adding this environment variable, you can access its value in your application through the process.env object. It is a good idea to stop and start your local development server when making changes to environment variables as they typically only get loaded as the application boots. You can do this by hitting ctrl + c, then running npm run dev again.

\n\n\n\n

Configure Apollo Client

\n\n\n\n

Now that our Next.js application can access the URL of our WordPress site, we can create the Apollo Client instance that will be used to request data.

\n\n\n\n

In the blank /lib/apollo.js file, add the following code:

\n\n\n\n

import { ApolloClient, InMemoryCache } from \"@apollo/client\";\n\n\nexport const client = new ApolloClient({\n  uri: `${process.env.NEXT_PUBLIC_WORDPRESS_API_URL}/graphql`,\n  cache: new InMemoryCache(),\n});

\n\n\n\n

The first line of code here imports ApolloClient and InMemoryCache from the @apollo/client package.

\n\n\n\n

Then, below that we create a new instance of ApolloClient and export that as a variable named client. When we create the new client, we pass in a configuration object with uri and cache properties. The uri property should point the GraphQL client to your server’s /graphql endpoint, and the cache property gets assigned to a new InMemoryCache instance. The caching features of Apollo Client help speed up your application by storing query results in memory.

\n\n\n\n

With our client fully configured, the next step is to make our client available across your application using the ApolloProvider component.

\n\n\n\n

Wrap App in ApolloProvider

\n\n\n\n

Even though we have a valid ApolloClient object in /lib/apollo.js we still need to import it somewhere and make it available inside of our React application’s component tree. To do this, we’ll make some changes to the code at the root of our Next.js application, which is contained in the /pages/_app.js file.

\n\n\n\n

Inside of this file, add the following import statements. These pull in the client we created in the previous step and the ApolloProvider component that Apollo Client provides.

\n\n\n\n

import { ApolloProvider } from \"@apollo/client/react\";\nimport { client } from \"../lib/apollo\";

\n\n\n\n

Next, wrap the base page <Component> inside of the ApolloProvider component, passing the configured client as a prop:

\n\n\n\n

function MyApp({ Component, pageProps }) {\n  return (\n      <ApolloProvider client={client}>\n        <Component {...pageProps} />\n      </ApolloProvider>\n    )\n}

\n\n\n\n

Wrapping your app in an ApolloProvider gives you the ability to use the React hooks that Apollo Client provides, such as useQuery(), useLazyQuery(), useMutation() etc. from anywhere in your app. While we won’t be leveraging those hooks in this app, I recommend that if you’re working with Apollo Client in a React project, you wrap your app in an ApolloProvider so that you’re able to do so when needed.

\n\n\n\n

Make the Index Page Dynamic

\n\n\n\n

Now that we have a fully configured data fetching client available in our component tree, we can start making the pages of this tutorial site dynamic. To get started, open up the /pages/index.js file in your editor.

\n\n\n\n

Next.js uses a routing method know as page-based routing, meaning that generally, the routes of your site or application will correspond to the file structure of your /pages folder. In this case, the index.js file at the root of the directory corresponds to the root your your site, which should be available at the / URL. In the next step, we’ll look at creating dynamic route paths, but be sure to read the Next.js docs on routing for more details.

\n\n\n\n

Page Components

\n\n\n\n

When Next.js processes a page-based route, it expects the default export of a given route to be a React component, commonly referred to as a “page component”. Let’s take a look at the default export for our /pages/index.js route:

\n\n\n\n

export default function Home({ posts }) {\n  return (\n    <div className=\"container\">\n      <Head>\n        <title>Headless WP Next Starter</title>\n        <link rel=\"icon\" href=\"favicon.ico\"></link>\n      </Head>\n\n      <main>\n        <h1 className=\"title\">\n          Headless WordPress Next.js Starter\n        </h1>\n\n        <p className=\"description\">\n          Get started by editing <code>pages/index.js</code>\n        </p>\n\n        <div className=\"grid\">\n          {\n            posts.map((post) => {\n              return (\n                <PostCard key={post.id} post={post}></PostCard>\n              )\n            })\n          }\n        </div>\n      </main>\n\n      <Footer></Footer>\n    </div>\n  )\n}

\n\n\n\n

In this case, we are exporting a component named HomePage by default, and the HomePage component accepts a props object, on which we are expecting a posts property to exist. The return value of this component is a JSX Element, and can contain other nested components, like PostCard and Footer, for example.

\n\n\n\n

Inside of the HomePage component, we’ve written an expression that iterates over the posts array, passing the data for each post into a PostCard component, and then returning that custom component. The result that gets rendered to the page looks like this, a card for each post in the array:

\n\n\n\n

\n\n\n\n

While this example is pulling in placeholder dummy data, in the next step we’ll work towards populating these components with data fetched from our WordPress site.

\n\n\n\n

Data Fetching

\n\n\n\n

Now that we have a general understanding of how the HomePage component works, let’s take a look at how that component gets its data. First, let’s add two import statements to the top of our /pages/index.js file:

\n\n\n\n

import { client } from '../lib/apollo';\nimport { gql } from \"@apollo/client\";

\n\n\n\n

In some styles of React development, particularly styles using client-side rendering, each component can be responsible for sourcing its own data. However, since we are using Next.js to statically generate our pages, all of the data sourcing code for this example will be inside of the getStaticProps() function.

\n\n\n\n

With the placeholder data in use, the getStaticProps() function in the index.js file should look like this:

\n\n\n\n

export async function getStaticProps(){\n  const posts = await getAllPosts()\n  return {\n    props: {\n      posts\n    }\n  }\n}

\n\n\n\n

To make this page dynamic, we will replace the call to the getAllPosts function with a GraphQL query that pulls data from a WordPress site.

\n\n\n\n

Constructing a GraphQL Query

\n\n\n\n

The first step in integrating our Next.js app and WordPress site is to construct a GraphQL query that returns the data we’ll need to build out the rest of our features. One of the most common ways to build GraphQL queries is using the built-in GraphiQL IDE that comes with WPGraphQL.

\n\n\n\n

In the WordPress Admin sidebar, head to GraphQL > GraphiQL IDE to get started.

\n\n\n\n

Using the QueryComposer feature of the GraphiQL IDE allows developers to manually select fields from the GraphQL scheme to add to a query and then run that query against the site’s database in real time. This can be extremely useful to you as your application parses responses from GraphQL so that developers know exactly how to traverse the response object and its properties.

\n\n\n\n

Once you compose your query, you can hit the play icon (▶️) to execute it and see the data that gets returned in the right-most pane.

\n\n\n\n

\n\n\n\n

Once you settle on a query that meets all of your requirements, you can copy/paste the query that you composed into your app.

\n\n\n\n

Running the Query

\n\n\n\n

Back in /pages/index.js, replace the code inside of the getStaticProps() function with the code below.

\n\n\n\n

Here, we pass the query we composed to a gql tagged template literal (“gql” followed by two backticks) and assign the return value to a GET_POSTS variable.

\n\n\n\n

export async function getStaticProps(){\n\n  // Paste your GraphQL query inside of a gql tagged template literal\n  const GET_POSTS = gql`\n    query AllPostsQuery {\n      posts {\n        nodes {\n          title\n          content\n          date\n          uri\n        }\n      }\n    }\n  `;\n  // Here we make a call with the client and pass in our query string to the \n  // configuration objects 'query' property\n  const response = await client.query({\n    query: GET_POSTS\n  });\n  // Once we get the response back, we need to traverse it to pull out the \n  // data we want to pass into the HomePage\n  const posts = response?.data?.posts?.nodes; \n\n  return {\n    props: {\n      posts\n    }\n  }\n}

\n\n\n\n

This code example is heavily commented with what each line is doing, so walk through each line and make sure you comprehend what is happening before moving on. If you save and refresh your browser window, the index page of our demo site should now look something like this (if you installed placeholder content from the repo):

\n\n\n\n

\n\n\n\n

From here you could experiment with adding additional fields to your GraphQL query and work on surfacing that data on the PostCard component, which can be found in the /components/PostCard.js file.

\n\n\n\n

In the next step, we’ll do something similar to create a post detail page using dynamic routing in Next.js.

\n\n\n\n

Make the Post Page Dynamic

\n\n\n\n

Dynamic Route Overview

\n\n\n\n

Dynamic routing is a huge concept in web applications and is necessary to build a dynamic site of any real size, and even WordPress core has methods of structuring dynamic routes paths via permalinks. With dynamic routing, we can extract information from a URL structure and use that information to generate a customized response.

\n\n\n\n

Let’s look at the following examples:

\n\n\n\n

/blog/getting-started-with-vue\n/blog/react-overview\n\n/blog/[title]

\n\n\n\n

Above we have a pretty typical link structure, with several posts branching off the /blog path. When each of these URLs gets visited, the application receiving the request can access the value of the [title] section of the route and use that value to produce a request, by querying the database for a post with a title that matches the value in the URL.

\n\n\n\n

Next.js accomplishes dynamic routing by requiring a naming convention for our page component files. If you create a file called /pages/[uri].js, you can access the value of the requested route and extract the uri to be used inside of your application. Let’s see how this works in practice in our SlugPage component, which is the default export from the /pages/[uri].js file.

\n\n\n\n

If we look at the code inside of the getStaticProps() function, we can see that this example accepts a params object as an argument:

\n\n\n\n

export async function getStaticProps({ params }){\n    const response = await getPostByUri(params.uri)\n    const post = response?.data?.post\n    return {\n      props: {\n        post\n      }\n    }\n  }

\n\n\n\n

In this case, the params object contains information about our dynamic URL segments. If we access the params.uri property, we get the value of that URL segment for a particular request that we can pass into our data fetching code. Behind the scenes, the getPostByUri() function filters an array of posts for the one that matches the uri of the request. Understanding how to work with dynamic routes is a core concept for building web applications and in turn working with headless WordPress, so be sure to review the Next.js docs linked above for additional info on this feature.

\n\n\n\n

Pre-rendering Static Paths

\n\n\n\n

When using static generation with getStaticProps(), Next.js will generate a static version of our page when it starts serving our application. For a component like our HomePage, that is easy for Next.js to do since it doesn’t require any input from the user in the form of a dynamic URL segment– the home page is the same for every user and is only available at one URL.

\n\n\n\n

When we create a dynamic route, like we did in /pages/[uri].js, it’s impossible for Next.js to pre-generate those pages without knowing what the value of params.uri will be. To solve this problem, anytime we use getStaticProps() with a dynamic route segment like [uri] we are also required to export a function called getStaticPaths(),which looks like this:

\n\n\n\n

export async function getStaticPaths(){\n    const paths = ['/narwal','/kombucha', '/baby-unicorns']\n    return {\n        paths,\n        fallback: 'blocking'\n    }\n}

\n\n\n\n

One of the properties on the object returned by this function should be an array of any paths that we want to pre-render to static assets. This allows Next.js to process those resources before a user visits those pages. Any dynamic route that hasn’t been pre-rendered using this method will be generated when the first user requests the URL and then made available for all subsequent requests. That means that it’s also valid to return an empty array of paths in this function:

\n\n\n\n

export async function getStaticPaths(){\n    const paths = []\n    return {\n        paths,\n        fallback: 'blocking'\n    }\n}

\n\n\n\n

In this example, all of the pages will be generated on the first user request, which means that first request will typically be much slower than subsequent request because Next.js has to both render and serve the page.

\n\n\n\n

However, this function gives the developer a ton of flexibility in how they optimize their applications. For example, you could hard code an array of your most popular paths to optimize those posts, but it is also possible to create that array programmatically in a variety of ways, like getting the URIs for your ten most recent blog posts.

\n\n\n\n

Add GraphQL Query

\n\n\n\n

To update the data fetching code in our dynamic SlugPage component, we’ll first need to add two import statements to the top of the file:

\n\n\n\n

import { client } from '../lib/apollo';\nimport { gql } from \"@apollo/client\";

\n\n\n\n

With these new imports available, we can start constructing our query in the GraphiQL IDE. Open the IDE, create a new query named GetPostByURI and select post from the list of schema objects. If you check the $id and $idType options, GraphiQL will help you begin to parameterize your query so that we can pass in variables in the next step. Add the fields you see below to your query and then copy the code in the query composer window.

\n\n\n\n

\n\n\n\n

Back in the /pages/[uri].js file, we can now replace the code in the getStaticProps function to use this query:

\n\n\n\n

export async function getStaticProps({ params }){\n  const GET_POST = gql`\n    query GetPostByURI($id: ID!) {\n      post(id: $id, idType: URI) {\n        title\n        content\n        date\n        author {\n          node {\n            firstName\n            lastName\n          }\n        }\n      }\n    }\n  `\n  //  the params argument for this function corresponds to the dynamic URL segments\n  //  we included in our page-based route. So, in this case, the `params` object will have\n  //  a property named `uri` that contains that route segment when a user hits the page\n  const response = await client.query({\n    query: GET_POST,\n    variables: {\n      id: params.uri\n    }\n  })\n  const post = response?.data?.post\n  return {\n    props: {\n      post\n    }\n  }\n}

\n\n\n\n

One change you may need to make to your GraphQL query would be to change $id: ID = \"/narwal\" to $id: ID! so that we can pass that in as a variable to ApolloClient when we actually make the query. To pass those variables, pass client.query a second variables object where each variable is a property that corresponds to the variable in the query. In this case, id: params.uri will replace the $id in our GraphQL query.

\n\n\n\n

With our data fetching code in place, refresh your browser and visit the page for one of your posts. If you used the XML export file in earlier steps, you should see something like this if you visit the /narwal path in your browser.

\n\n\n\n

\n\n\n\n

Done! 🎉

\n\n\n\n

Congratulations on creating a headless WordPress site! We covered a lot of ground in this crash course. Hopefully you now have a good understanding of how you can leverage tools like Next.js and WPGraphQL to build headless WordPress sites.

\n\n\n\n

If for any reason you weren’t able to follow along with the steps outlined in this post, you can access the finished state of our example app on this GitHub branch.

\n\n\n\n

Looking for a place to host your headless WordPress project? Check out WP Engine’s Atlas platform.

\n"},{"__typename":"Post","id":"cG9zdDo0MDg=","slug":"headless-wordpress-tech-stack-options","seo":{"__typename":"PostTypeSEO","readingTime":4,"title":"Headless WordPress Tech Stack Options - Headless WordPress Developers"},"title0":"Headless WordPress Tech Stack Options","uri":"/headless-wordpress-tech-stack-options/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMQ==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/8ee8d4ed6d4b3a916be500eb1bcf03f4?s=96&d=mm&r=g"},"name":"Grace Erixon","description":"---\r\ntitle: Associate Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"excerpt0":"

\n","content0":"\n

A headless WordPress architecture disconnects the frontend from the backend, which opens up many possibilities for the technologies that a developer can use to build the client. The WordPress backend serves platform-agnostic JSON data that can be used to create multiple web apps, iOS or Android apps, desktop apps, content management tools, etc; the possibilities are endless! However, this leaves you as the developer with many more choices to make. To build a standard headless WordPress web app, a developer will need to select an API layer (WPGraphQL or the WordPress REST API), choose from an ever-growing list of frontend JavaScript frameworks, potentially add a solution for building content models, and decide on a hosting platform. The flexibility of the tech stack options for headless WordPress can feel intimidating! Let’s break down these choices and give recommendations on what WP Engine’s Developer Relations team feels to be the “happy path” for headless WordPress developers.

\n\n\n\n

API Layer

\n\n\n\n

The interaction between the WordPress backend and the custom frontend framework happens through the API layer. The API layer will call the content from the WordPress backend and push it to whatever frontend technology the developer chooses. The two options for the API layer are the WordPress REST API or WPGraphQL.

\n\n\n\n

The REST API comes bundled with WordPress, however, the data access pattern that it requires can be slow for the developer because it requires multiple round trips to reconstruct a fully modeled post, for example. REST requires each resource to have its own endpoint, so to get a post with the author and category would be three separate API calls. In contrast, WPGraphQL allows us to ask for a post with the author and category all in one request. Because of this, WPGraphQL is our preferred API layer. WPGraphQL is a free plugin that provides an extendable GraphQL schema and API for your WordPress site. WPGraphQL is faster than the REST API because it gets the exact data that is asked for as well as fewer functions executing through query optimization, less data downloading, more efficient data loading, and multiple resources included in a single request. For more information, watch this in-depth comparison of WPGraphQL and the WordPress REST API.

\n\n\n\n

Our recommendation: WPGraphQL

\n\n\n\n

JavaScript Frameworks

\n\n\n\n

A headless architecture gives developers the freedom to choose from any frontend technology stack, with frontend JavaScript frameworks being the most popular. Some of the most popular frontend JavaScript frameworks include React, Vue.js, Svelte, and Angular. New JavaScript frameworks are being released all the time, so this list is nowhere near comprehensive.

\n\n\n\n

Many JavaScript frameworks are used in conjunction with meta-frameworks that add solutions for routing, server-side rendering, etc. React is used in conjunction with Next.js, Vue.js is used in conjunction with Nuxt.js, and Svelte is used in conjunction with SvelteKit. Gatsby is another popular meta-framework.

\n\n\n\n

WP Engine has developed Faust.js, a JavaScript framework built on top of React and Next.js. Faust.js was created specifically to support headless WordPress web applications. It supports authentication and post previews out of the box, provides convenient built-in React hooks for accessing WordPress data, and more.

\n\n\n\n

Our recommendation: Faust.js, used in conjunction with React and Next.js

\n\n\n\n

Content Modeling Tool

\n\n\n\n

When developing your headless web application, you may find that you need to add extra content fields or custom post types. This often requires cobbling together and configuring several separate plugins to accomplish. For example, you could pair the Advanced Custom Fields plugin to add the custom fields and the ACF to REST API plugin to properly structure the API calls or a WPGraphQL extension.

\n\n\n\n

The Atlas Content Modeler plugin is headless-native, so its’ integration is tighter and more straightforward due to its focus on headless. ACM allows developers to easily create content models and have them automatically added to the WPGraphQL schema. Developers can then start querying for their data immediately.

\n\n\n\n

Our recommendation: Atlas Content Modeler

\n\n\n\n

Plugins

\n\n\n\n

When using WordPress, there are always tons of options for what plugins are available. The general rule for headless WordPress is that as long as a plugin does not touch the frontend of the WordPress site then it will work normally.

\n\n\n\n

Good candidates for headless plugins will usually work well with WPGraphQL. Check out this list of WPGraphQL extension plugins.

\n\n\n\n

The FaustWP plugin ensures that your WordPress site runs smoothly as a headless CMS. This includes things like smart content redirects and enabling post previews. Check out this list of plugins that are built for headless.

\n\n\n\n

Our recommendation: FaustWP and whatever else you need!

\n\n\n\n

Hosting Platform

\n\n\n\n

Since the frontend and the backend are separate in headless WordPress, you would generally have to host each separately and configure them to communicate. Atlas is the only platform on which you can host both your headless WordPress backend and your JavaScript frontend app and easily manage both from a single dashboard.

\n\n\n\n

Our recommendation: Atlas

\n\n\n\n

What’s Next?

\n\n\n\n

The flexibility of tech stack options is one of the major benefits of headless WordPress for a developer! While the decisions can feel intimidating at first, hopefully, this blog post has helped you make educated choices about what you’re building!

\n\n\n\n

Stay tuned for our next blog post to walk through building a simple headless WordPress app with Next.js & WPGraphQL!

\n"},{"__typename":"Post","id":"cG9zdDozNjY=","slug":"when-should-i-use-headless-wordpress","seo":{"__typename":"PostTypeSEO","readingTime":15,"title":"When Should I Use Headless WordPress? - Headless WordPress Developers"},"title0":"When Should I Use Headless WordPress?","uri":"/when-should-i-use-headless-wordpress/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMg==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/a64abda82041a00e479ecc2b156d7947?s=96&d=mm&r=g"},"name":"Jeff Everhart","description":"---\r\ntitle: Sr. Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"excerpt0":"

\n","content0":"\n

As developers, we are often asked to weigh in on architectural decisions or provide recommendations on the technical direction of new projects. For developers new to decoupled architectures using headless CMSs it can be difficult to fully articulate the pros and cons to your teammates, managers, or potential clients. This article attempts to answer some of those questions so you know when you should or should not reach for headless WordPress. If you need a refresher on what this site development methodology looks like, check out this resource on headless WordPress.

\n\n\n\n

Common Reasons to Use Headless WordPress

\n\n\n\n

Improved Performance and Perceived Performance

\n\n\n\n

\n\n\n\n

When asked about their plans to transition to a headless CMS, many developers cite performance as a key driver for that decision. While actual performance is important to popular site ranking metrics, many modern JavaScript frameworks can provide perceived performance benefits as well, meaning that sites feel faster and more responsive to users even though that may not be the case.

\n\n\n\n

Load Fewer Assets with Code Splitting

\n\n\n\n

In traditional WordPress, CSS and JavaScript code are typically enqued across an entire site without convenient methods to decide when and where to load particular assets. In some cases, WordPress decides for you what libraries to include (we’re looking at you jQuery).

\n\n\n\n

Modern JavaScript build practices and frameworks utilize various approaches to code splitting, which helps you load only the code that is required to render a particular page, view, or component. The goal of code splitting, whether route-based or component-based, is to lower the size of the initial payload that the user has to download.

\n\n\n\n

Less code shipped to the browser means less bandwidth and less time spent parsing and executing JavaScript that isn’t required for the current page. All of that makes your site more performant on less powerful mobile devices or devices with a slow connection.

\n\n\n\n

While there are certainly ways to optimize your assets using traditional WordPress through caching, minification, and other optimization techniques, the tooling available in JavaScript frameworks gives developers some additional methods to tackle performance issues.

\n\n\n\n

Faster Page Transitions

\n\n\n\n

If your chosen frontend framework supports client-side or hybrid routing, you can create extremely fast page transitions since your app is only loading and re-rendering the parts of the page that have changed. While the actual load time of a client-side page navigation vs. a statically generated and heavily cached page may not differ substantially, this is an example of where a user could perceive client-side routing as more performant because they don’t experience the visual interruption of a full page refresh as they browse the site.

\n\n\n\n

Improved Core Web Vitals

\n\n\n\n

When using pre-packaged themes for traditional WordPress, it can be difficult to achieve healthy scores on Core Web Vitals without lots of customization by a developer. These metrics are described by Google in the guide on Web Vitals:

\n\n\n\n

“Core Web Vitals are the subset of Web Vitals that apply to all web pages, should be measured by all site owners, and will be surfaced across all Google tools. Each of the Core Web Vitals represents a distinct facet of the user experience, is measurable in the field, and reflects the real-world experience of a critical user-centric outcome.”
Philip Walton, Web Vitals

\n\n\n\n

Core Web Vitals include things like Largest Contentful Paint (LCP), First Input Delay (FID), Cumulative Layout Shift (CLS), which all address important aspects of how performant and usable web pages are as they load on user devices. Most frontend frameworks come designed to address many of these vital site metrics, and improved Core Web Vitals is one common benefit of adopting a headless architecture.

\n\n\n\n

Total Rendering Control (SSG/SSR/CSR)

\n\n\n\n

In the world of the web, everything eventually comes full circle, including patterns of rendering sites in the browser, or the process of translating your data and component tree into the HTML, CSS, and JavaScript that browsers can understand and display. Over the last several years, this area has seen massive technical innovation along with whiplash-inducing changes in opinion on ‘best practices,’ from rendering on the server, to rendering everything on the client with SPAs, to pre-generating static HTML files using static site generation (SSG).

\n\n\n\n

While there isn’t enough room in this post to look at all of the rendering patterns in detail, WordPress’ method of server-side rendering (SSR) hasn’t changed at all during that period, which is a testament to the stability of its core platform. However, one of the chief benefits of the headless approach is that teams can adopt WordPress as a stalwart CMS, while also taking advantage of the innovation happening alongside popular frontend frameworks to create best-in-class experiences for both the creators and consumers of digital content.

\n\n\n\n

Improved Developer Experience

\n\n\n\n

\n\n\n\n

In the broader community of web and software developers, we see the rapid creation of new technical patterns, tools, and methodologies that as a whole move the industry forward. Yet, in many ways, WordPress’ core software seems to take the opposite approach and prioritizes stability over constant reinvention. As a result, many developers have to reconcile two different approaches to development that feel out of step with one another. In many ways, adopting WordPress as a headless CMS can help bridge this gap, pairing a stable and trusted open source CMS with a JavaScript environment that lends itself to rapid innovation.

\n\n\n\n

Component-based Architecture

\n\n\n\n

One of the characteristics of most JavaScript frameworks is that they lend themselves to component-based design and development. When compared to traditional WordPress theme development which centers around PHP page templates and perhaps partials that are created from repeated components, component-based development offers many benefits to large teams and enterprises where this headless site will be only one piece of a larger ecosystem of properties tied to a specific brand.

\n\n\n\n

For example, let’s imagine a SaaS company that has invested heavily in building out a brand compliant component library for their flagship product. By adopting a headless architecture, their development team is able to reuse code and components across multiple web properties, thus speeding up development time and ensuring brand consistency.

\n\n\n\n

Leverage the JS Ecosystem

\n\n\n\n

Just like the ecosystem for WordPress themes and plugins, the JavaScript ecosystem is equally diverse. By building on modern web development tools, you gain access to a variety of new components that can enhance the quality of your site and the user experience.

\n\n\n\n

While the WordPress plugin repository helps traditional users accomplish these goals, the choices available can be limited if we are looking for very specific functionality. For developers, using the REST API or GraphQL API to integrate with WordPress can remove some of the overhead associated with creating a traditional plugin, especially if the scope and configurability of the component is limited.

\n\n\n\n

This can be a huge productivity boost depending on the skills of your development team, but if you need to rely on individual WordPress plugins for specific functionality, not all of them are built to support the REST API or GraphQL. The headless community has worked hard to create extensions to popular plugins that allow them to more seamlessly integrate into decoupled frontends, so be sure to conduct a thorough needs assessment of your required functionality before starting a new headless project.

\n\n\n\n

Flexible Data Sourcing

\n\n\n\n

\n\n\n\n

Perhaps the most compelling reason to consider WordPress as a headless CMS is the flexibility of data sourcing. While WordPress is sometimes known primarily as blogging software, it also has the ability to extend its basic type system to create complex types, relationships, and hierarchies. Making this data available via REST or GraphQL APIs gives organizations a ton of flexibility in how they construct and populate data stores.

\n\n\n\n

Write Once, Publish Everywhere

\n\n\n\n

One of the most important features of a headless CMS is that they enable omnichannel experiences, meaning your single CMS provides the same data to your website, other clients like iOS or Android apps, or Internet of Things connected devices. WordPress comes with a robust REST API out of the box that is powering more and more critical experiences on the platform, but using plugins like WPGraphQL you can also turn your WordPress site into a powerful GraphQL API to gain the performance benefits of that technology.

\n\n\n\n

Ingest Data from Multiple Sources

\n\n\n\n

Headless architecture allows you to easily combine your WordPress source data with data from other APIs to provide richer customer experiences. Depending on your frontend application choices, you may have some flexibility in how you do this. For example, if you are building a Next.js application, you could write code in getStaticProps or getServerSideProps hooks that queries both your WordPress API (GraphQL or REST) in addition to the other services required to produce a particular page. On the other hand, you could also extend WordPress using a plugin to create a custom REST endpoint in PHP that gets added to your WordPress site’s existing API or GraphQL schema. If your site will end up displaying data from a variety of sources and WordPress is one of them, then that could be a good reason to pursue a headless architecture.

\n\n\n\n

Model Complex Data Types

\n\n\n\n

Although WordPress has a great reputation as a tool for personal blogs or small websites, it is also a powerful CMS that can be extended to model complex types of content. While many organizations have taken advantage of that feature in traditional WordPress PHP templates, the data can also be exposed via API to be used on any publishing channel. In the past, creating these complex data types required either a collection of related plugins or lots of custom code, but Atlas Content Modeler provides an integrated approach to both managing custom content types and making them available to decoupled clients.

\n\n\n\n

Increased Security

\n\n\n\n

\n\n\n\n

Over the years, WordPress has gotten what is perhaps an unfair reputation for bad security practices, which becomes a common objection to using it in favor of other CMSs. However, one of the benefits of decoupled systems is both a separation of concerns and system resiliency, both of which help to create more secure environments.

\n\n\n\n

Reduce Surface Area for Attackers

\n\n\n\n

Since the backend WordPress instance isn’t available to the public in headless deployments, it is more difficult for bad actors to target that instance specifically. In many cases, it can be impossible to tell that a headless site is using WordPress at all since there are no public artifacts in the source code or network calls that give away this information unless your client-side code connects directly to your WordPress instance.

\n\n\n\n

Importantly, if a hacker can’t tell you are using WordPress, they won’t know to try any WordPress-specific exploits. Additionally, since many headless deployments are less reliant on themes and plugins, they become more secure because outdated themes and plugins are most often the source of vulnerabilities rather than the core WordPress software itself.

\n\n\n\n

Additionally, since the frontend application and CMS are now decoupled, you could apply advanced networking techniques to promote security. For example, you could disallow traffic to your CMS from IP addresses outside of an approved list that includes your corporate office and frontend app, that way you have complete control over the connections made to your CMS.

\n\n\n\n

Possible DDoS Resiliency

\n\n\n\n

Since the system that renders your content (e.g. your frontend app) is separate from the system that stores and manages it (e.g. WordPress CMS), you gain an amount of resilience in the face of a Distributed Denial of Service attack. In many cases, a DDoS attack has the potential to take an entire traditional CMS offline, meaning both the user-facing site and the administration panel will be taken offline. While there is no guarantee that a headless site won’t experience a total outage as well, some of the patterns used to develop headless frontends, like static site generation, help to mitigate the load across the system.

\n\n\n\n

When Should I Use Traditional WordPress Instead?

\n\n\n\n

Even though there are lots of use cases that support adopting a headless architecture using the WordPress CMS, there are still very clear cases where it makes more sense to deploy a traditional WordPress site. Let’s take a look at some of those reasons, below.

\n\n\n\n

Clients Expect to Take Advantage of Certain Traditional WordPress Tools and Features

\n\n\n\n

One of the reasons WordPress has grown so dominant in the CMS marketplace is because of how easy it is for a user to customize their site on their own using plugins, theme customizations, or other types of page builders. In a headless approach, the data stored in the CMS is separated from its presentation to the user.

\n\n\n\n

In practice, this means that most visual enhancements that get applied to a page or component via plugins, custom blocks, or page builders will not get displayed by default in a headless deployment. When starting a new project or talking with a potential client, understanding their expectations around their ability to change or customize the site design will be an important indicator of which approach is best suited to their needs. Here are just a few indicators that a traditional WordPress installation might be best:

\n\n\n\n

You Want to Use Full Site Editing Capabilities

\n\n\n\n

One of the latest changes to traditional WordPress is the addition of full site editing capabilities to the WordPress admin area. The goal of this change is to bring the capabilities of many page builder plugins/themes directly into WordPress core through things like block themes and block patterns. This new paradigm gives site users a far greater depth of control over the visual output of a site without having to dive into code.

\n\n\n\n

In many ways headless WordPress and full site editing exist on opposite ends of a spectrum. On one end you have headless WordPress, where WordPress merely acts as a data repository for your site content, and on the other end full site editing allows users to more fluidly compose site elements using blocks and block patterns. If you or your client wants to be able to use full site editing features, sticking with a traditional WordPress installation might be your best bet.

\n\n\n\n

You Need Plugins for Visual Site Components

\n\n\n\n

Given the specific requirements of headless WordPress, some plugins may not work well in this environment out of the box. For example, any plugin that adds visual output to a post or page will most likely not display correctly without additional configuration. If we use a traditional carousel plugin as an example, these types of plugins typically output an HTML structure to the post content and enqueue additional CSS and JS assets to style the page and make it interactive. When getting the post content through the REST or GraphQL API, we only have the HTML content to work with, leaving the developer to recreate or port over the CSS and JS needed to make the carousel function properly.

\n\n\n\n

If you know that your development team will need to use plugins to create site components or that the client expects to add plugins on their own to customize the site visuals, that is a good signal that a traditional WordPress installation is likely best for your project.

\n\n\n\n

Overall Cost or Project Timeline Prohibit Headless

\n\n\n\n

Even though there are many benefits of using the WordPress CMS as the backbone of a headless architecture, just the nature of creating a decoupled application means that it comes with additional technical complexity that should be considered. Unless you or your agency specialize in headless application development, developing a headless website may require additional labor to actually deploy and additional maintenance cost to keep updated. A platform like Atlas can help offset some of these costs by giving development teams one central place to develop, deploy, and maintain headless sites, but other hosting providers can leave your resources scattered across a number of other services.

\n\n\n\n

Often project timeline and overall cost are evaluated against some of the benefits that a headless architecture may provide, and not every client may be willing and able to make those trade-offs. If this is the case, a traditional WordPress approach may be best.

\n\n\n\n

Your Developers Aren’t Fluent with Tech Required for Headless

\n\n\n\n

While traditional WordPress offers the promise of no-code or low-code website development, headless WordPress relies on developers skilled in the technologies required to deliver content to your particular channel. For the web, that skill set typically involves an intermediate to advanced understanding of modern JavaScript frameworks like Vue, React, Svelte, or Angular, experience consuming data from REST or GraphQL APIs in that given framework, and other frontend related technologies like HTML, CSS, and web accessibility.

\n\n\n\n

Depending on your chosen deployment location, you may also require developers with a backend focus that have experience developing custom REST API endpoints in PHP or modifying the GraphQL API schema. However, WP Engine’s Atlas platform helps abstract away some of the configuration details needed to create and extend the CMS administration and authoring experience.

\n\n\n\n

Regardless of your hosting environment, your developers will need to also be skilled in using GitHub to manage codebases, as most headless hosting environments use this strategy to manage deployments.

\n\n\n\n

Wrapping Up

\n\n\n\n

Throughout this blog post, we’ve discussed several key scenarios where we should consider using WordPress as a headless CMS. When compared to traditional WordPress deployments, headless approaches have the following potential benefits:

\n\n\n\n

Improve actual performance and perceived performance by adopting innovations happening in the frontend framework space
Create more enjoyable and productive patterns for developers
Serve complex data to omnichannel clients using REST or GraphQL APIs
Provide increased security and system resilience

\n\n\n\n

However, it’s also important to consider other factors for when a traditional WordPress deployment might be right for you or your client:

\n\n\n\n

The client expects to have some element of visual, aesthetic, or functional control over the site through affordances in the WordPress dashboard (e.g. plugins, page builders, custom blocks, theme customizer options)
The overall cost or timeline of a headless deployment is prohibitive to you or your client
You or your developers aren’t fluid in the tech required to manage or create headless experiences

\n\n\n\n

At the end of the day, one of the reasons WordPress has gained such widespread adoption as a platform is because of the almost infinite ability to offer more options. In this way, adopting WordPress as a headless CMS is just another option that you have as a developer when the challenges you are facing could be solved by taking a headless approach.

\n"},{"__typename":"Post","id":"cG9zdDozNTc=","slug":"what-is-headless-wordpress","seo":{"__typename":"PostTypeSEO","readingTime":3,"title":"What is Headless WordPress? - Headless WordPress Developers"},"title0":"What is Headless WordPress?","uri":"/what-is-headless-wordpress/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjoxMQ==","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/8ee8d4ed6d4b3a916be500eb1bcf03f4?s=96&d=mm&r=g"},"name":"Grace Erixon","description":"---\r\ntitle: Associate Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"excerpt0":"

In order to understand what a “headless WordPress” website architecture is, it’s important to first understand what a traditional WordPress architecture looks like. Let’s compare each of these approaches. Traditional WordPress Traditionally, a content management system (CMS), such as WordPress, would handle both the frontend and backend of a website. Users typically interact with a […]

\n","content0":"\n

\n\n\n\n

Traditional WordPress

\n\n\n\n

Traditionally, a content management system (CMS), such as WordPress, would handle both the frontend and backend of a website.

\n\n\n\n

Users typically interact with a traditional WordPress site like this:

\n\n\n\n

Publisher: Creates and manages content such as blog posts and pages inside of WordPress.
Developer: Writes code to control how the site looks and functions using PHP and WordPress’ Theme API.
Website Visitor: WordPress generates the HTML page that is sent to the website visitor.

\n\n\n\n

\n\n\n\n

In this “coupled” CMS architecture, WordPress provides the content management capabilities to publishers, and it is also responsible for serving HTML pages to website visitors.

\n\n\n\n

Headless WordPress

\n\n\n\n

A headless CMS uses a “decoupled” architecture, where the frontend and backend are managed separately. Publishers still manage content in WordPress, but WordPress is no longer responsible for generating HTML pages. Instead, a separate JavaScript-based frontend application is responsible for generating and serving the HTML pages that are served to website visitors. The frontend JS app typically uses WPGraphQL or the REST API to “pull” data out of WordPress and use it to render the pages of the website.

\n\n\n\n

Users typically interact with a headless WordPress site like this:

\n\n\n\n

Publisher: Creates and manages content such as blog posts and pages inside of WordPress (the same as in a traditional WP architecture).
Developer: Writes code to control how the site looks and functions using JavaScript. A framework such as Next.js (+ Faust.js), Nuxt or SvelteKit is often used to power this frontend application.
Website Visitor: The frontend JavaScript app generates the HTML page that is sent to the website visitor.

\n\n\n\n

A headless WordPress architecture allows publishers to continue to benefit from the great publishing experience that WordPress provides. At the same time, it also also allows developers and website visitors to take advantage of technical capabilities that modern JavaScript applications bring to the table.

\n\n\n\n

What’s Next?

\n\n\n\n

Hopefully this post has given you a good sense of what headless WordPress is and how it differs from a traditional WordPress architecture.

\n\n\n\n

At this point, you may be thinking “Okay, but when should I use WordPress as a headless CMS?” Stay tuned for a blog post on that very topic, coming soon!

\n"},{"__typename":"Post","id":"cG9zdDozMzk=","slug":"introducing-the-headless-wordpress-developer-roadmap","seo":{"__typename":"PostTypeSEO","readingTime":4,"title":"Introducing the Headless WordPress Developer Roadmap - Headless WordPress Developers"},"title0":"Introducing the Headless WordPress Developer Roadmap","uri":"/introducing-the-headless-wordpress-developer-roadmap/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}},"avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Manager, Developer Relations\r\n---"}},"excerpt0":"

The trend of pairing a headless content management system (CMS) with a decoupled frontend JavaScript app is rapidly gaining popularity. It allows developers to source their data from various services, build out static pages that can be hosted “at the edge” for lightning-quick load times, work with cutting-edge frontend tech, and more. What do you […]

\n","content0":"\n

\n\n\n\n

What do you get when you combine that trend with the fact that WordPress now powers over 43% of the web? A market that handsomely rewards those skilled at building headless WordPress apps.

\n\n\n\n

To help visualize this momentum, check out this trend line for the “headless wordpress” keyword on explodingtopics.com, a site that measures trending topics:

\n\n\n\n

Beyond the technical benefits, JavaScript is the most commonly used programming language at 69.7 percent and one of the most in-demand languages in the software engineering job market. It is also increasingly relevant in the WordPress space. In his 2015 State of the Word address, Matt Mullenweg famously gave developers in the WordPress community the homework assignment to “learn JavaScript, deeply.” In the years since, the Gutenberg block editor has been written in JavaScript, merged into WordPress core, and an ecosystem of JS-powered Gutenberg blocks has emerged.

\n\n\n\n

All of that means that if you’re a developer, there’s never been a better time to get familiar with writing modern JavaScript and learn to work with WordPress as a headless CMS.

\n\n\n\n

Headless WordPress Developer Roadmap

\n\n\n\n

If gaining this skill set is something you’ve meant to do but haven’t, I challenge you to make 2022 the year you learn how to build and launch headless WordPress apps! 🚀

\n\n\n\n

To help you achieve that goal, the WP Engine Developer Relations team is introducing our Headless WordPress Developer Roadmap! This resource will give you an excellent foundation. You’ll be able to leverage what you’ve learned to build and deploy real, production headless WordPress applications. We really hope you find it beneficial.

\n\n\n\n

Tech Stack

\n\n\n\n

With headless WordPress, there are many different tech choices you can make. You can choose from various frontend app frameworks, select an API layer (WPGraphQL vs. REST API), select a solution for building content models, choose a hosting platform, and so on. With so many options, even getting started seems daunting. That’s why for our Developer Roadmap, we’re focusing on what we feel to be the “happy path” for doing headless WordPress. We’ll keep things as simple as possible by sticking with this set of consistent tools:

\n\n\n\n

Frontend Framework: Faust.js

\n\n\n\n

Faust is built on top of React and Next.js and is tailor-made to support headless WordPress apps. It supports authentication and post previews out of the box, provides convenient React hooks for accessing WordPress data, and more.

\n\n\n\n

API Layer: WPGraphQL

\n\n\n\n

WPGraphQL provides several benefits over the WordPress REST API for headless apps and is our preferred API layer.

\n\n\n\n

Content Modeling Tool: Atlas Content Modeler

\n\n\n\n

ACM allows developers to easily create content models and have them automatically added to the WPGraphQL schema. Developers can then start querying for their data immediately. ACM represents a giant leap forward compared to other solutions that involve cobbling together and configuring several separate plugins to accomplish the same thing.

\n\n\n\n

Hosting Platform: Atlas

\n\n\n\n

Atlas is the only platform on which you can host both your headless WordPress backend and your JavaScript frontend app, and easily manage both from a single dashboard.

\n\n\n\n

Content

\n\n\n\n

We plan to cover topics like these:

\n\n\n\n

What is headless WordPress, and when does it make sense to use that architecture over traditional WordPress?
Tools to build apps powered by Faust.js, WPGraphQL and Atlas Content Modeler
How to implement core website features such as navigation menus, Gutenberg blocks, search, comments, post previews, etc.
Where to host and deploy headless WordPress apps

\n\n\n\n

What Do You Want to Learn?

\n\n\n\n

Are there specific topics you’d like us to cover in the roadmap? Please reach out to let us know! We’d love to hear your feedback!

\n"},{"__typename":"Post","id":"cG9zdDozMjA=","slug":"the-when-and-where-of-rendering","seo":{"__typename":"PostTypeSEO","readingTime":9,"title":"The When and Where of Rendering - Headless WordPress Developers"},"title0":"The When and Where of Rendering","uri":"/the-when-and-where-of-rendering/","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":""}}}},"excerpt0":"

\n","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=","slug":"atlas-content-modeler-walk-through","seo":{"__typename":"PostTypeSEO","readingTime":17,"title":"Atlas Content Modeler Walk-Through - Headless WordPress Developers"},"title0":"Atlas Content Modeler Walk-Through","uri":"/atlas-content-modeler-walk-through/","author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo2","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"KellenMace"}},"avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/00afaa4d1d51e8714e55d744cdf68de3?s=96&d=mm&r=g"},"name":"Kellen Mace","description":"---\r\ntitle: Manager, Developer Relations\r\n---"}},"excerpt0":"

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. In this post, we’ll walk through all the features that ACM […]

\n","content0":"\n

\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"}],"pageInfo":{"__typename":"WPPageInfo","hasNextPage":true,"endCursor":"YXJyYXljb25uZWN0aW9uOjI5Ng=="}},"seo":{"schema":{"siteUrl":"https://developers.wpengine.com","__typename":"SEOSchema","siteName":"Headless WordPress Developers","companyLogo":{"__typename":"MediaItem","id":"cG9zdDoxNjg=","altText":""}},"__typename":"SEOConfig"}},"selections":[[["0-1-2","post0"],["3-4-5","title0"],["6-4-5","excerpt0"],["7-4-8","avatar0"],["9-4-5","content0"],["10-11-12","youtubeVideos0"],["13-11-14","posts0"],["13-15-14","posts1"],["0-16-2","post1"],["0-17-2","post2"],["0-18-2","post3"],["0-19-2","post4"],["0-20-2","post5"],["21-22-23","headlessWordPressPlugins0"],["10-24-12","youtubeVideos1"],["0-25-2","post6"],["0-26-2","post7"],["0-27-2","post8"],["0-28-2","post9"],["0-29-2","post10"],["0-30-2","post11"],["0-31-2","post12"],["0-32-2","post13"],["0-33-2","post14"],["0-34-2","post15"],["0-35-2","post16"],["10-36-12","youtubeVideos2"],["0-37-2","post17"],["0-38-2","post18"],["0-39-2","post19"],["0-40-2","post20"],["0-41-2","post21"],["0-42-2","post22"],["0-43-2","post23"],["0-44-2","post24"],["0-45-2","post25"],["10-46-12","youtubeVideos3"],["0-47-2","post26"],["0-48-2","post27"]],[["post",0],["{\"id\":\"what-is-atlas-content-modeler\",\"idType\":\"SLUG\"}",1],["{\"id\":\"ID!\",\"idType\":\"PostIdType\",\"asPreview\":\"Boolean\"}",2],["title",3],["{}",4],["{\"format\":\"PostObjectFieldFormatEnum\"}",5],["excerpt",6],["avatar",7],["{\"size\":\"Int\",\"forceDefault\":\"Boolean\",\"rating\":\"AvatarRatingEnum\"}",8],["content",9],["youtubeVideos",10],["{\"first\":3}",11],["{\"first\":\"Int\",\"last\":\"Int\",\"after\":\"String\",\"before\":\"String\",\"where\":\"RootQueryToYoutubeVideoConnectionWhereArgs\"}",12],["posts",13],["{\"first\":\"Int\",\"last\":\"Int\",\"after\":\"String\",\"before\":\"String\",\"where\":\"RootQueryToPostConnectionWhereArgs\"}",14],["{\"first\":9}",15],["{\"id\":\"headless-wordpress-authentication-native-cookies\",\"idType\":\"SLUG\"}",16],["{\"id\":\"gravity-forms-in-headless-wordpress-gatsby\",\"idType\":\"SLUG\"}",17],["{\"id\":\"build-a-simple-headless-wordpress-app-with-react-wpgraphql\",\"idType\":\"SLUG\"}",18],["{\"id\":\"headless-wordpress-with-vue-and-nuxt-js\",\"idType\":\"SLUG\"}",19],["{\"id\":\"rendering-patterns-in-headless-wordpress\",\"idType\":\"SLUG\"}",20],["headlessWordPressPlugins",21],["{\"first\":500}",22],["{\"first\":\"Int\",\"last\":\"Int\",\"after\":\"String\",\"before\":\"String\",\"where\":\"RootQueryToHeadlessWordPressPluginConnectionWhereArgs\"}",23],["{\"first\":12}",24],["{\"id\":\"graphql-code-generator-for-wpgraphql\",\"idType\":\"SLUG\"}",25],["{\"id\":\"gutenberg-in-headless-wordpress-render-blocks-as-html\",\"idType\":\"SLUG\"}",26],["{\"id\":\"introducing-the-headless-wordpress-developer-roadmap\",\"idType\":\"SLUG\"}",27],["{\"id\":\"gutenberg-in-headless-wordpress-wpgraphql-gutenberg\",\"idType\":\"SLUG\"}",28],["{\"id\":\"what-is-headless-wordpress\",\"idType\":\"SLUG\"}",29],["{\"id\":\"previews-in-headless-wordpress-using-nextjs\",\"idType\":\"SLUG\"}",30],["{\"id\":\"headless-wordpress-tech-stack-options\",\"idType\":\"SLUG\"}",31],["{\"id\":\"when-should-i-use-headless-wordpress\",\"idType\":\"SLUG\"}",32],["{\"id\":\"crash-course-build-a-simple-headless-wordpress-app-with-next-js-wpgraphql\",\"idType\":\"SLUG\"}",33],["{\"id\":\"building-an-e-commerce-site-using-shopify-headless-wordpress-nextjs-and-chakra-ui-part-1-setup\",\"idType\":\"SLUG\"}",34],["{\"id\":\"work-with-gravity-forms-in-headless-wordpress\",\"idType\":\"SLUG\"}",35],["{\"first\":12,\"after\":\"YXJyYXljb25uZWN0aW9uOjI5Mg==\"}",36],["{\"id\":\"the-when-and-where-of-rendering\",\"idType\":\"SLUG\"}",37],["{\"id\":\"atlas-content-modeler-walk-through\",\"idType\":\"SLUG\"}",38],["{\"id\":\"set-up-wordpress-as-a-headless-cms\",\"idType\":\"SLUG\"}",39],["{\"id\":\"state-of-headless-development\",\"idType\":\"SLUG\"}",40],["{\"id\":\"building-an-e-commerce-site-using-shopify-headless-wordpress-nextjs-and-chakra-ui-part-1-setup~\",\"idType\":\"SLUG\"}",41],["{\"id\":\"apollo-client-cache-rehydration-in-next-js\",\"idType\":\"SLUG\"}",42],["{\"id\":\"what-is-headless\",\"idType\":\"SLUG\"}",43],["{\"id\":\"custom-content-types-in-headless-wordpress\",\"idType\":\"SLUG\"}",44],["{\"id\":\"introduction-to-graphql-in-wordpress\",\"idType\":\"SLUG\"}",45],["{\"first\":12,\"after\":\"undefined\"}",46],["{\"id\":\"wp-login.php\",\"idType\":\"SLUG\"}",47],["{\"id\":\"null\",\"idType\":\"SLUG\"}",48]],[[0,27],[3,0],[6,0],[7,0],[9,0],[10,3],[13,1],[21,0]],"v0"]}

Server Side Rendering (SSR)

Client Side Rendering (CSR)

Static Site Generation (SSG)

Incremental Static Regeneration (ISR)

Conclusion

Code Sandbox Overview

React App Overview

Create an Apollo Client Instance

Implement Apollo Provider Component

Import useQuery() Hook in PostsList

Compose GraphQL Query Using the GraphiQL IDE

Format Query with gql

Fetch Data with the useQuery() Hook

Making PostPage.js Dynamic

Construct GET_POST_BY_SLUG Query

Call useQuery() Hook from PostPage.js

Done! 🎉

Prerequisites

Configure Your WordPress Site

Create a WordPress Site with Local

Install Plugins and Check Settings

Check Permalink Settings

Install WPGraphQL and Enable Debug Mode

Import Placeholder Content

Get Your Next.js App Running Locally

Connect Apollo Client to WordPress

Create a .env File

Configure Apollo Client

Wrap App in ApolloProvider

Make the Index Page Dynamic

Page Components

Data Fetching

Constructing a GraphQL Query

Running the Query

Make the Post Page Dynamic

Dynamic Route Overview

Pre-rendering Static Paths

Add GraphQL Query

Done! 🎉

API Layer

JavaScript Frameworks

Content Modeling Tool

Plugins

Hosting Platform

What’s Next?

Common Reasons to Use Headless WordPress

Improved Performance and Perceived Performance

Load Fewer Assets with Code Splitting

Faster Page Transitions

Improved Core Web Vitals

Total Rendering Control (SSG/SSR/CSR)

Improved Developer Experience

Component-based Architecture

Leverage the JS Ecosystem

Flexible Data Sourcing

Write Once, Publish Everywhere

Ingest Data from Multiple Sources

Model Complex Data Types

Increased Security

Reduce Surface Area for Attackers

Possible DDoS Resiliency

When Should I Use Traditional WordPress Instead?

Clients Expect to Take Advantage of Certain Traditional WordPress Tools and Features

You Want to Use Full Site Editing Capabilities

You Need Plugins for Visual Site Components

Overall Cost or Project Timeline Prohibit Headless

Your Developers Aren’t Fluent with Tech Required for Headless

Wrapping Up

Traditional WordPress

Headless WordPress

What’s Next?

Headless WordPress Developer Roadmap

Tech Stack

Frontend Framework: Faust.js

API Layer: WPGraphQL

Content Modeling Tool: Atlas Content Modeler

Hosting Platform: Atlas

Content

What Do You Want to Learn?

Define “render”…

Import `useQuery()` Hook in `PostsList`

Format Query with `gql`

Fetch Data with the `useQuery()` Hook

Making `PostPage.js` Dynamic

Construct `GET_POST_BY_SLUG` Query

Call `useQuery()` Hook from `PostPage.js`