{"cache":{"posts1":{"__typename":"RootQueryToPostConnection","nodes":[{"__typename":"Post","id":"cG9zdDo0NTQ=","uri":"/headless-wordpress-with-remix-and-tailwind-css/","seo":{"__typename":"PostTypeSEO","readingTime":12,"title":"Headless WordPress with Remix and Tailwind CSS - 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":"Headless WordPress with Remix and Tailwind CSS","slug":"headless-wordpress-with-remix-and-tailwind-css","excerpt0":"

One of the benefits of headless WordPress architecture is that it allows us total flexibility in how we want to develop our frontend website. Given this flexibility, it allows headless developers to experiment with new and emerging technologies easily. In this post, we’ll take a look at a newer framework in the JavaScript world and […]

\n","content0":"\n

\n\n\n\n

Create a new Remix project from scratch, or customize this starter, and hook it up to WordPress using Apollo Client
Implement loader functions in Remix to query data
Create dynamic routes in Remix to display individual posts by post uri
Implement different Link prefetching strategies based on your use-case
Understand the tradeoffs of using Tailwind CSS to style block editor content

\n\n\n\n

Getting Started with the Remix WordPress Starter

\n\n\n\n

To get us started, I’ve created a pretty basic headless WordPress site using the latest version of Remix, all of the needed dependencies, and some styling with Tailwind CSS. If you run the following commands in your terminal, you should end up with a fully running site in your browser that is pulling data from a remote WordPress site.

\n\n\n\n

git clone https://github.com/JEverhart383/remixing-wordpress.git\ncd remixing-wordpress\nnpm install\nnpm run dev

\n\n\n\n

The rest of this article will walk through some of the different parts of this codebase to explain how this Remix starter is created and discuss specific aspects of Remix that developers coming from other frameworks may want to be aware of.

\n\n\n\n

As prerequisites, you should be familiar with React, WPGraphQL, and ideally one meta-framework like Next.js, Nuxt, Svelete, or Gatsby. For refreshers on those foundational topics, you can reference our Headless WordPress Developer Roadmap.

\n\n\n\n

Loading Data in the Index Page

\n\n\n\n

Like other full stack frameworks, Remix uses a page-based routing system, which means that we can access the code that renders our index route in the /app/routes/index.jsx file. This file exports a default function named Index that returns a React component that represents this route:

\n\n\n\n

import Post from \"../components/Post\"\nimport Header from \"../components/Header\"\nimport { useLoaderData } from \"@remix-run/react\"\nimport { gql } from \"@apollo/client\"\nimport { client }  from \"../lib/apollo\"\n\nexport async function loader (){\n  const PostsQuery = gql`\n        query GetPosts {\n            posts {\n                nodes {\n                    title\n                    content\n                    date\n                    slug\n                }\n            }\n        }\n    `\n    const response = await client.query({\n        query: PostsQuery\n    })\n\n    const posts = response?.data?.posts?.nodes\n    return posts\n}\n\n\nexport default function Index() {\n  const posts = useLoaderData();\n  return (\n    <div>\n      <Header title=\"Home Page\" ></Header>\n        <div className=\"grid gap-8 grid-cols-1 lg:grid-cols-3 p-6\">\n          {posts.map(post => {\n              return (\n                <Post post={post} key={post.title}></Post>\n              )\n            })}\n        </div>\n    </div>\n  );\n}

\n\n\n\n

In this case our Index function creates a grid of our site’s posts by mapping over them and creating individual Post components. In addition to exporting the route component as a default, we also export an async function named loader, which is Remix’s convention for loading data into components.

\n\n\n\n

When this route is requested by the browser, the Remix framework runs the code inside of the loader function on the server, and then the component can access that data inside of the component using the useLoaderData hook. In our example above, we import a pre-configured instance of ApolloClient and execute a GraphQL query, returning that data inside the loader function.

\n\n\n\n

To change the example GraphQL origin to your own WordPress site. You can change the url property in the /app/lib/apollo.js file:

\n\n\n\n

import { ApolloClient, InMemoryCache} from \"@apollo/client\";\n\nexport const client = new ApolloClient({\n    uri: 'Swap your URL here',\n    cache: new InMemoryCache()\n})

\n\n\n\n

How Does Remix Standout on Data Loading

\n\n\n\n

When looking at something like Next.js in comparison, there are a number of different ways to load data into page components for static or server-rendered pages, like getStaticProps, but also methods for having components request their own data from your GraphQL origin on the client using Apollo’s useQuery hook for example.

\n\n\n\n

While there are a lot of different rendering methods available to modern developers, splitting the responsibility of data fetching across multiple different domains (the client and the server) adds to the API surface area that developers contend with as they develop applications and can lead to additional challenges.

\n\n\n\n

In particular, the Remix team talks about credential management being improved by loading all data on the server. Since the client never makes requests to sensitive origins on its own, we don’t need to worry about exposing API keys or proxying request manually since Remix already acts as our proxy. Personally, I’m a huge fan of this selling point as someone who’d developed a lot of SPAs.

\n\n\n\n

In addition, client-side fetching can sometimes fall victim to a waterfall of network requests, where a parent might fetch its own data, but then pass data into a child component that triggers its own data requests based on the data passed in by the parent component.

\n\n\n\n

Because there is a centralized mechanism for loading data into components in Remix using loader functions, it is easier to coordinate and parallelize some of those network requests to avoid this waterfall loading pattern.

\n\n\n\n

As a developer, I tend to appreciate opinionated software more than software that provides a lot of different approaches. Having the opportunity to evaluate a lot of different JavaScript frameworks as a part of my job, I can personally understand the issues Remix is trying to solve here. But it’s also a divergence from a common practice in the JavaScript world and thus not for everyone or every situation.

\n\n\n\n

Prefetching with Link Components in Remix

\n\n\n\n

Now that we have a good understanding of how data loading works in Remix, let’s take a look at how the framework implements prefetching with Link components. Link prefetching isn’t unique to Remix, as its a part of the browser platform and also used by Next.js, but in some ways it works in tandem to help eliminate any negative impacts of loading data on the server.

\n\n\n\n

Let’s take a look at the Post component in /app/components/Post.jsx to examine this in more detail:

\n\n\n\n

import { Link } from \"@remix-run/react\"\n\nexport default function Post({post}){\n    return (\n        <Link prefetch=\"intent\" to={`/posts/${post.slug}`}>\n            <div className=\"flex \n            items-center \n            bg-gradient-to-r\n            from-cyan-500 \n            to-blue-500 \n            p-8 \n            rounded-lg \n            text-white \n            transition-all \n            hover:-translate-y-1 \n            hover:scale-105\"\n            >\n                <div>\n                    <h2 className=\"font-semibold text-2xl\">{post.title}</h2>\n                    <p>{ new Date(post.date).toLocaleDateString() }</p>\n                </div>\n            </div>\n        </Link>\n\n    )\n}

\n\n\n\n

In this code snippet, we are returning the JSX element that represents our post card inside of the post grid on our index page. This card is wrapped in a Link component provided by the Remix framework, and here we provide it both a dynamic navigation path via the to prop as well as a prefetch=\"intent\" attribute. It is this feature of the Link component in Remix that allows us to enable prefetching on user intent, which occurs when a user interacts with a Link component via hover or focus, or on render, which prefetches all available routes on the page.

\n\n\n\n

As you can see in the example GIF below, as we hover over the Link components, Remix loads all of the resources (JS, CSS, and data) associated with each route so that the routes are available immediately when the user clicks on them.

\n\n\n\n

\n\n\n\n

While Remix isn’t the first or only framework to implement prefetching, it pairs very nicely with the server-loaded data in my opinion. Given that Remix can load my application’s data in the background, I’m less inclined to stress about the amount of network requests it takes to get that data since it’s still immediately available for my users.

\n\n\n\n

When examining Link components using the prefetch=\"render\"attribute, we see that there is the potential of much more network activity using this method. As soon as those components have rendered, they will request additional data from the server, which can be great if you want to prime certain high priority routes.

\n\n\n\n

\n\n\n\n

When compared to the prefetching available with Next.js, Remix doesn’t necessarily bring anything controversial to the table but does adopt a a pattern of defaults for prefetching that is different from Next.js. Frankly, I’m glad to see more frameworks give this technique consideration, as it can drastically improve the user experience during site navigation.

\n\n\n\n

Dynamic Routing in Remix

\n\n\n\n

Now that we’ve looked at how to render our Index page and use Link components to prefetch the data for our posts, let’s look at how Remix’s router makes that possible using dynamic routes.

\n\n\n\n

To construct dynamic page-based routes in Remix, we can add additional folders and files to our routes folder. In this case, we create a file called $slug.jsx inside of the /routes/posts directory, which creates a dynamic route segment that responds to browser requests for URLs like /posts/[post-slug-here]. When we do this, Remix makes $slug available as a variable inside of our loader function so we can use it to request data. We can see that played out in our page component for that route:

\n\n\n\n

import Header from \"../../components/Header\"\nimport { useLoaderData } from \"@remix-run/react\";\nimport { gql } from \"@apollo/client\"\nimport { client }  from \"../../lib/apollo\"\n\nexport async function loader ({params}) {\n  const slug = params.slug\n  const PostQuery = gql`\n    query GetPostBySlug($id: ID!) {\n        post(id: $id, idType: SLUG) {\n            date\n            content\n            title\n            slug\n        }\n    }\n  `\n\n  const response = await client.query({\n    query: PostQuery,\n    variables: {\n        id: slug\n    }\n  })\n\n  const post = response?.data?.post\n  return post\n}\n\nexport default function Index() {\n  const post = useLoaderData()\n  return (\n    <div>\n      <Header title=\"Home Page\" ></Header>\n        <main className=\"bg-gray-100 container mx-auto mt-6 p-6 rounded-lg\">\n            <h1 className=\"text-4xl\">{post.title}</h1>\n            <div className=\"text-2xl mt-4\">{new Date(post.date).toLocaleDateString()}</div>\n            <article className=\"mt-4 space-y-2\" dangerouslySetInnerHTML={{__html: post.content}}></article>\n        </main>\n    </div>\n  );\n}\n

\n\n\n\n

The loader function of our route components gives us access to any route params passed in by the user, but it can also access additional details actual HTTP request as well:

\n\n\n\n

export async function loader ({params, request}) {\n  const slug = params.slug\n  const url = new URL(request.url);\n  const search = url.searchParams.get(\"search\");\n// Do stuff with slug and search here\n}

\n\n\n\n

In our example above, we then use the value of params.slug to populate a GraphQL query for our specific WordPress post:

\n\n\n\n

export async function loader ({params}) {\n  const slug = params.slug\n  const PostQuery = gql`\n    query GetPostBySlug($id: ID!) {\n        post(id: $id, idType: SLUG) {\n            date\n            content\n            title\n            slug\n        }\n    }\n  `\n\n  const response = await client.query({\n    query: PostQuery,\n    variables: {\n        id: slug\n    }\n  })\n\n  const post = response?.data?.post\n  return post\n}

\n\n\n\n

It’s also worth noting at this point, that the data fetching code that runs inside of the loader function can be very flexible for the developer. It’s up to you in how to create and organize your data layer. In previous versions of this tutorial, I extracted all of the logic you see above into a single function in a separate file, so my loader looked like this with one additional import statement:

\n\n\n\n

import { getPostBySlug } from ../../lib/WordPressService\n\nexport async function loader ({params}) {\n  const slug = params.slug\n  return await getPostBySlug(slug)\n}

\n\n\n\n

This gives developers a ton of flexibility in determining the organizational practices for their application. If you’re a fan of colocating data fetching code in your route modules, you can do that, but if you prefer a different pattern Remix gives you the flexibility to do that as well.

\n\n\n\n

Supporting Tailwind CSS

\n\n\n\n

A common question that comes up on our Headless WordPress Discord server is how to use Tailwind CSS and X framework to develop WordPress sites. For this article, I wanted to look at that specifically to evaluate how Remix works with Tailwind CSS, but also so that I could explore a CSS framework I have little experience with.

\n\n\n\n

Luckily, both the Remix docs and the Tailwind CSS docs have guides on configuring the tools to work together, and I was able to get Tailwind support running very quickly.

\n\n\n\n

Since this article isn’t about Tailwind CSS per se, I’m going to focus on the important aspects of this framework for headless WordPress developers specifically. Tailwind CSS is a utility-first framework, which means that you essentially add utility classes to your HTML elements to style them. Our Post component is an example of this:

\n\n\n\n

\n<Link prefetch=\"render\" to={`/posts/${post.slug}`}>\n            <div className=\"flex \n            items-center \n            bg-gradient-to-r\n            from-cyan-500 \n            to-blue-500 \n            p-8 \n            rounded-lg \n            text-white \n            transition-all \n            hover:-translate-y-1 \n            hover:scale-105\"\n            >\n                <div>\n                    <h2 className=\"font-semibold text-2xl\">{post.title}</h2>\n                    <p>{ new Date(post.date).toLocaleDateString() }</p>\n                </div>\n            </div>\n        </Link>

\n\n\n\n

Using a series of CSS classes, we describe the display and styling of this element, but this involves adding classes to the actual HTML. While this pattern is really nice for creating components, it was a bit more challenging to think through how to style some of the block editor content that WordPress returns as a CMS.

\n\n\n\n

If we look at the route component for our $slug page, the article component is using React’s dangerouslySetInnerHTML attribute to output all of the rendered markup that makes up the post content:

\n\n\n\n

export default function Slug() {\n  const post = useLoaderData()\n  return (\n    <div>\n      <Header title=\"Home Page\" ></Header>\n        <main className=\"bg-gray-100 container mx-auto mt-6 p-6 rounded-lg\">\n            <h1 className=\"text-4xl\">{post.title}</h1>\n            <div className=\"text-2xl mt-4\">{new Date(post.date).toLocaleDateString()}</div>\n            <article className=\"mt-4 space-y-2\" dangerouslySetInnerHTML={{__html: post.content}}></article>\n        </main>\n    </div>\n  );\n}

\n\n\n\n

Because our WordPress editor content is essentially echoed out inside of the article element, we don’t have the opportunity to add Tailwind utility classes to that markup before or as it is rendered without doing some extra work.

\n\n\n\n

In other looks at styling block editor markup, we talk about importing WordPress npm packages to use native CSS, or even writing our own classes to match the markup. But both of those seemed at odds with the Tailwind philosophy of utility-first CSS.

\n\n\n\n

Tailwind would theoretically pair nicely if you are willing to either parse blocks from the HTML response, or use the WPGraphQL Gutenberg extension to create more formal components. This pattern would be very powerful, but does require another level of commitment.

\n\n\n\n

Tailwind CSS also has its own method of extracting classes using the @apply directive, which may give developers interested in exploring Tailwind with headless WordPress another avenue of targeting block editor markup. If I were to do a deeper project with Tailwind again, this is likely the avenue I would take. In theory, it would let us do something like this to style an image’s figure container:

\n\n\n\n

@layer components {\n  .wp-block-image {\n     @apply //our tailwind utility classes here;\n  }\n}

\n\n\n\n

For the purposes of this demo, I was able to make some basic styling changes with Tailwind just by relying on the targeting the parent article element, but this exercise may include some trial and error:

\n\n\n\n

<article className=\"mt-4 space-y-2\" dangerouslySetInnerHTML={{__html: post.content}}></article>

\n\n\n\n

Wrapping Up! 🎉

\n\n\n\n

Thanks for exploring Remix, Tailwind CSS, and headless WordPress with me in this article. If you want an example of 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":"cG9zdDo0NzQ=","uri":"/multi-lingual-headless-wordpress-with-next-js-and-wpgraphql-with-the-polylang-plugin/","seo":{"__typename":"PostTypeSEO","readingTime":17,"title":"Multi-Lingual Headless WordPress with Next JS and WPGraphQL with the Polylang plugin - Headless WordPress Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","id":"dXNlcjo3","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/c24a68b84c9ad2b53c633d14917d8298?s=96&d=mm&r=g"},"name":"Francis Agulto","description":null,"seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"title0":"Multi-Lingual Headless WordPress with Next JS and WPGraphQL with the Polylang plugin","slug":"multi-lingual-headless-wordpress-with-next-js-and-wpgraphql-with-the-polylang-plugin","excerpt0":"

In this walk-through tutorial, you will learn how to create a headless WordPress site with multi-lingual functionality using Next.js, Next.js internationalized routing, Polylang, WPGraphQL, and the WPGraphQL Polylang extension. This tutorial assumes a fundamental understanding of Node.js, React/Next.js and its data fetching methods and routing, WPGraphQL, Apollo Client and WordPress. Prerequisites Node.js and npm installed […]

\n","content0":"\n

\n\n\n\n

Prerequisites

\n\n\n\n

Node.js and npm installed
Code editor (Visual Studio Code is what I use)
A WordPress host with an install already spun up (WP Engine is my go to) or a free demo environment with Local.
A Github repository and account

\n\n\n\n

By the end of this tutorial, you will be able to:

\n\n\n\n

Use the Polylang Plugin with its WPGraphQL extension
Understand and use Internationalized routing in Next.js
Create a home page with multi-lingual posts content
Create single post detail page with multi-lingual post detail content

\n\n\n\n

The Polylang WordPress Plug-in

\n\n\n\n

The Polylang WordPress plugin enables multi-lingual site capability for numerous languages for your WordPress content. This is valuable because this allows you to create content and pages that are localized to your users that speak different languages. There is a pro version. For this tutorial, we are going to use the free version. Let’s install the Polylang plugin and quickly cover how it is traditionally used.

\n\n\n\n

Login to your WP Admin and Install Polylang/WPGraphQL extension

\n\n\n\n

Login to your WP Admin. From Plugins > Add new menu, search for WPGraphQL, install it then search for Polylang. It will be the first plugin that populates in the WordPress plugin directory. Install and activate the plugin.

\n\n\n\n

\n\n\n\n

Check Pretty Permalink Settings

\n\n\n\n

All of the code in this tutorial is set around having the Post name option selected for your permalink settings. To modify this setting, open the Settings > Permalinks menu in the WP Admin dashboard.

\n\n\n\n

\n\n\n\n

Once the plugin is activated, you will see a new item on the side menu called Languages. Navigate to Languages > Settings > URL modifications. Click to the options \"The language is set in pretty permalinks, Hide URL language information for default language, Remove /language/ in pretty permalinks.\" These three settings allows us to:

\n\n\n\n

have our language URL set to the directory of that language instead of a subdomain
hides the URL for our default language so it is not prepended by the code of that default
Removes the language in permalink so you don’t have the entire string of the language in the link

\n\n\n\n

\n\n\n\n

Install Polylang WPGraphQL Extension

\n\n\n\n

Next, we need to expose Polylang’s languages and translations for our post in the GraphQL schema. Go to the WPGraphQL for Polylang github repository page here: https://github.com/valu-digital/wp-graphql-polylang

\n\n\n\n

Once you do that, click on the green code button and go to the bottom of the dropdown and download the zip file.

\n\n\n\n

\n\n\n\n

Now go back to your WP admin. From the Plugins > Add new menu, go to the upload plugin button at the top. Click that and it will bring up a choose file box. Click on that and choose the zip file you downloaded from the WPGraphQL Polylang repository. You can now activate and install it.

\n\n\n\n

\n\n\n\n

Posts/Post Polylang Language Feature

\n\n\n\n

The next step is to start populating some data in English and Spanish. Navigate to Post in the menu. When you get into the Post edit page, you will now see an American and Mexican flag. This is the Polylang plugin at work. It ties a single post type together with its translations you add to it. In this case English and Spanish. I am a bit of a Star Wars nerd, hence the Star Wars content but you can use any content you like.

\n\n\n\n

\n\n\n\n

Once you click into the editor interface, you can see on the right side menu an option for Languages. When you click on that then click on the pencil icon, it lets you toggle between your English and Spanish versions.

\n\n\n\n

\n\n\n\n

\"\" — Spanish Translation of my default English Post

\n\n\n\n

That is how you setup the polylang plugin for WordPress in a traditional approach. When you visit your site, you will have the translator of your browser appear and you can toggle back and forth between English and Spanish. You can use whatever translator you want but bing translator is my favorite and most reliable.

\n\n\n\n

Constructing our GraphQL queries for translated posts

\n\n\n\n

Now that we have our posts data and extended the WordPress and Polylang data schema with a GraphQL layer using WPGraphQL and its extension, let’s build our queries to grab that multi-lingual post data from WordPress.

\n\n\n\n

In your WP Admin, go to the GraphiQL IDE and using the query composer, create this query shown here:

\n\n\n\n

\n\n\n\n

  query posts($language: LanguageCodeFilterEnum!)  {\n      posts(where: { language: $language }) {\n        edges {\n          node {\n            id\n            excerpt\n            title\n            slug\n            language {\n              code\n              locale\n            }\n          }\n        }\n      }\n      generalSettings {\n        title\n        description\n      }\n    }

\n\n\n\n

The Polylang plugin and WPGraphQL extension is allowing the $language to be the variable and requiring the LanguageCodeFilterEnum! to be the required value. When you query the language variable as an object in your composer and hit the play (➡️) it will give you all the posts in that language. Change it to \"ES\" to get Spanish translations back. Stoked!!🥳

\n\n\n\n

\n\n\n\n

Get Next JS Headless WP Starter cloned and running locally

\n\n\n\n

Since this is not a ground up tutorial on React and Next.js fundamentals, I have a demo site built for you already that utilizes Next.js and its data fetching capabilities with SSG, Apollo Client, Next.js Internationalized routing and Dynamic Routing. Go to your terminal and clone down the repository with this shell command:

\n\n\n\n

git clone git@github.com:Fran-A-Dev/nextjs-polylangwpgql.git

\n\n\n\n

After cloning, run npm install and open the files. The file structure in my Next.js starter has a components folder pages folder, lib folder, public folder, and a styles folder. I have scaffolded this starter to include static site generation data fetching method, the Apollo Client instance, dynamic post page routing and Next.js internationalized routing.

\n\n\n\n

Next.js Internationalized Routing

\n\n\n\n

Now that you have the starter site cloned, let’s break down things on the front end starting with internationalized routing on Next.js. When you are doing Headless WordPress and have users visiting your site that speak different languages, internationalizing your content is crucial to having a great user experience.

\n\n\n\n

We started this tutorial learning how to internationalize our content in WordPress traditionally and decoupling with WPGraphQL. In this next section, we will put it all together by connecting it with our front end and explore its internationalization feature. There are many different approaches to doing internationalization with Next.js. In our tutorial we are going to use router and link to switch translated content from WordPress.

\n\n\n\n

Next.js makes it seamless and easy to set up internationalization through a configuration object with the property i18n and within that object, you define your key which is locale with the default locale you want and its translations. Locale is the syntax used to define language and is a UTS identifier for standardized format for defining locations and language. In this case, English is the default and Spanish is the translated. Navigate to next.config.js file in the root of the project to see the code.

\n\n\n\n

module.exports = {\n  reactStrictMode: true,\n  i18n: {\n    locales: [\"en\", \"es\"],\n    defaultLocale: \"en\",\n  },\n};

\n\n\n\n

Configuring this allows Next.js to know what available locales we have in our app and each page when it gets rendered.

\n\n\n\n

Link to filter between languages

\n\n\n\n

Now that Next.js knows what languages by locales we have, we need to set up a link we can click on to filter between the languages on posts. Go to components/Navbar.js in the project. You should see this code within the file:

\n\n\n\n

import Link from \"next/link\";\nimport { useRouter } from \"next/router\";\nimport styles from \"../components/Navbar.module.css\"\n\nexport default function Navbar() {\n  const { locale: activeLocale, locales, asPath } = useRouter();\n\n  const availableLocales = locales.filter((locale) => locale !== activeLocale);\n\n  return (\n    <div className=\"container\">\n      <nav>\n        <ul>\n          <li>\n            <Link href=\"/\">\n              <a className={styles.home}>Home</a>\n            </Link>\n          </li>\n       \n        </ul>\n        <ul>\n          {availableLocales.map((locale) => {\n            return (\n              <li key={locale}>\n                <Link href={asPath} locale={locale}>\n                  <a className={styles.toggle}>{locale.toUpperCase()}</a>\n                </Link>\n              </li>\n            );\n          })}\n        </ul>\n      </nav>\n    </div>\n  );\n}

\n\n\n\n

Let’s break this file down and explain what Next.js is doing here. First, we need to program a way to list all the locales available, which locale the user is currently active on and the actual path of that locale. I am doing this by using the destructured useRouter hook with next/router imported at the top of the file with this line:

\n\n\n\n

import { useRouter } from \"next/router\";

\n\n\n\n

Once that is imported, I set up my router, I put a new constant at the top of the component and destructure to extract all the locale constant variables that are supported in my application:

\n\n\n\n

const { locale: activeLocale, locales, asPath } = useRouter();

\n\n\n\n

The locale variables seen above are all my locales, the actual active locale that the user will be on when viewing the page and the path that reflects the locale that they are on. The next step is to only show the user the locales that are not active so that the user can know what locale they can link to besides their current default on the page.

\n\n\n\n

To accomplish this, I created a constant and called it availableLocales. I set it equal to locales and I filter through that array of locales. Filtering through that array of locales, we return only the locales that are not equal the active one.

\n\n\n\n

const availableLocales = locales.filter((locale) => locale !== activeLocale);

\n\n\n\n

Now that is done, I need to pass this into my return statement in my list of links to make it an actual Link with next/link to display a clickable link which will act as our toggle between our two different locales with the correct path as shown in these lines:

\n\n\n\n

         <li>\n            <Link href=\"/\">\n              <a className={styles.home}>Home</a>\n            </Link>\n          </li>\n       \n        </ul>\n        <ul>\n          {availableLocales.map((locale) => {\n            return (\n              <li key={locale}>\n                <Link href={asPath} locale={locale}>\n                  <a className={styles.toggle}>{locale.toUpperCase()}</a>\n                </Link>\n              </li>

\n\n\n\n

Breaking this down more granularly, in the <ul> I take my available locales constant and map through it returning the <li> list item, and inside I replace the value within the <a> tag with locale as the value and make the letters upper case.

\n\n\n\n

Now focusing in the Link component in Next.js, it already has built in locale changing capabilities.

\n\n\n\n

<Link href={asPath} locale={locale}>

\n\n\n\n

What is happening here is I added a new prop of locale and I set it equal to locale to change the locale from English to Spanish and vise versa. Then, we have to pass the link it should navigate to in relation to where the user is currently located. So we use the asPath variable from our useRouter hook that we destructured and in the href we set it equal to asPath. Now that this is set, the user can click on the link in the Navbar to toggle back on forth for the proper language and its path.

\n\n\n\n

Once I finished this Navbar.js file, I wrapped the component in the pages >_app.js file so my entire app has access to it across the pages.

\n\n\n\n

Apollo Client/GraphQL setup

\n\n\n\n

This project does use apollo and GraphQL. In this demo, I chose to just create a lib folder with a apollo-client.js file to make an apollo instance. I also did not use .env.local which is a Next.js convention to not show environment variables and allow Next to detect those. In this demo’s case, I am directly putting that endpoint into the function.

\n\n\n\n

\n\n\n\n

Adding our GraphQL Queries

\n\n\n\n

In the previous section, we enabled Next.js internationalization functionality and added a Link in our Navbar that allows users to toggle the available locales or languages on the site. Lastly, we need to add the queries we made with WPGraphQL in our WordPress admin to our front end.

\n\n\n\n

Multi-Lingual Posts on the Home Page

\n\n\n\n

Remember our GraphQL query we made with the language variable at the beginning of this walk-through tutorial? Go to the pages/index.js/ file and here we see it at the bottom being queried within our getStaticProps function:

\n\n\n\n

export async function getStaticProps({ locale }) {\n  const apolloClient = getApolloClient();\n\n  const language = locale.toUpperCase();\n\n  const data = await apolloClient.query({\n    query: gql`\n    query posts($language: LanguageCodeFilterEnum!)  {\n      posts(where: { language: $language }) {\n        edges {\n          node {\n            id\n            excerpt\n            title\n            slug\n            language {\n              code\n              locale\n            }\n          }\n        }\n      }\n      generalSettings {\n        title\n        description\n      }\n    }\n    `,\n    variables: {\n      language,\n    },\n  });

\n\n\n\n

You can see with the above code snippet that we are querying for all posts and their different languages tied to their default English setting. We are using Apollo client for the client side help to fetch this data along with setting the constant of const language = locale.toUpperCase();to provide and call the filter we have that we made within the Navbar.

\n\n\n\n

WPGraphQL/Polylang Single Post query

\n\n\n\n

We have our project set up now where we have our home page displaying all of our posts with the ability to click the link at the top of the navbar and switch paths between English and Spanish.

\n\n\n\n

The next thing we need to do is create a query in our GraphiQL IDE back in the WP Admin to get a single post and its translation. Heading back into our query composer, create a query that looks like this:

\n\n\n\n

\n\n\n\n

This query is asking for the single post type with the variable being the slug, with the fields we want to grab along with the available translation and the language being the variable. When you query your variables via slug and language and press play in the GraphiQL IDE, you will get back the single post you want by its slug and its available translated version.

\n\n\n\n

Dynamic Route Page and Single Post Query

\n\n\n\n

The final steps we need to walk through are the dynamic routes page in our Next.js front end and setting up the query we just made for the single post to show up. This will allow users to click on the post they want to see on the home page, route them to that single post’s detail page dynamically. When they are on the post detail page, users can continue to be able to filter between English and Spanish.

\n\n\n\n

Navigate back to the Next.js project and go to pages/posts/ [postsSlug].js. At the bottom of the file within getStaticProps, you will see our query:

\n\n\n\n

export async function getStaticProps({params, locale}) {\nconst { postSlug } = params;\nconst language = locale.toUpperCase();\n  \nconst apolloClient = getApolloClient();\n\n  const data = await apolloClient.query({\n    query: gql`\n    query PostBySlug($slug: String!, $language: LanguageCodeEnum!) {\n      generalSettings {\n        title\n      }\n      postBy(slug: $slug) {\n        id\n        content\n        title\n        slug\n        translation(language: $language) {\n          id\n          slug\n          content\n          title\n          language {\n            locale\n            slug\n          }\n        }\n      }\n    }

\n\n\n\n

This is similar to our Home page query. The difference is we now are asking for a single post with our dynamic routes page and path to the that particular post detail page. When displayed, we will see our specific fields to that single post we asked for with the ability to toggle back and forth on its language translations.

\n\n\n\n

Next, let’s focus on our getStaticPaths function, we can statically pre-build the static paths with our pre-built pages on our app since we have dynamic routes for the details of each page.

\n\n\n\n

export async function getStaticPaths({ locales }) {\n  const apolloClient = getApolloClient();\n\n  const data = await apolloClient.query({\n    query: gql`\n      {\n        posts(first: 10000) {\n          edges {\n            node {\n              id\n              title\n              slug\n            }\n          }\n        }\n      }\n    `,\n  });

\n\n\n\n

I destructured the context of locales so I can have all the locales variables.

\n\n\n\n

Now we are creating all the paths for only the existing default routes here.

\n\n\n\n

const paths = posts.map(({ slug }) => {\n    return {\n      params: {\n        postSlug: slug,\n      },\n    };\n  });\n

\n\n\n\n

What we need to do is have a way to add on the locales for our existing paths. This is done here:

\n\n\n\n

  return {\n    paths: [...paths,\n      ...paths.flatMap((path) => {\n        return locales.map((locale) => {\n          return {\n            ...path,\n            locale,\n          };

\n\n\n\n

In the return statement, I have an array open and I am spreading out the paths that already exist which are default routes. The trick here is to spread out another instance of paths and then I use the flatMap method to go deeper into another level of array with the locales. The flatMap method is like the map method but it allows you to flatten out arrays that have a top level array, in this case the default paths and flatten them out into the top level array.

\n\n\n\n

Then for each path, it returns a new map statement mapping through the locales and returning the path and the locale together.

\n\n\n\n

Run the demo locally

\n\n\n\n

We are almost done. All you have to do now is go to your terminal, run npm run dev and get your browser up on localhost:3000.

\n\n\n\n

You should see this on your browser with the Navbar showing the available locale and language not in use which is Spanish:

\n\n\n\n

\n\n\n\n

Now click on the link and it should translate and you should see the same posts displayed with their Spanish translations:

\n\n\n\n

\n\n\n\n

Click on one of the Spanish post displayed and it will take you to the details page of that post and its path.

\n\n\n\n

\n\n\n\n

Lastly, click again on the link atop the EN link at the top of the Navbar to switch this post detail page to its default English version:

\n\n\n\n

\n\n\n\n

Done!! Stoked! 🎉

\n\n\n\n

We are finished with this walk through tutorial! Jamstoke! With this tutorial, we hope you take away the importance of adding multi-language capability on your sites and apps, leveraging tools like WPGraphQL and all its extensions like Polylang, Next.js internationalized routing as well as Next.js fundamental features.

\n\n\n\n

This is just one way of approaching multi-language Headless WordPress. I would love to hear your thoughts and your own approaches and builds. Hit me up in our Discord!

\n\n\n\n

Here is the demo once again so you can follow along, make it your own and add on to it if you like on my GitHub.

\n\n\n\n

Click here if you want to see the site live! If you are looking for headless WordPress hosting, my site is on the Atlas platform.

\n"},{"__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=","slug":"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"},"title0":"Crash Course: Build a Simple Headless WordPress App with React & WPGraphQL","uri":"/build-a-simple-headless-wordpress-app-with-react-wpgraphql/","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 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=","slug":"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"},"title0":"Crash Course: Build a Simple Headless WordPress App with Next.js & WPGraphQL","uri":"/crash-course-build-a-simple-headless-wordpress-app-with-next-js-wpgraphql/","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":"

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

Getting Started with the Remix WordPress Starter

Loading Data in the Index Page

How Does Remix Standout on Data Loading

Prefetching with Link Components in Remix

Dynamic Routing in Remix

Supporting Tailwind CSS

Wrapping Up! 🎉

Prerequisites

The Polylang WordPress Plug-in

Login to your WP Admin and Install Polylang/WPGraphQL extension

Check Pretty Permalink Settings

Install Polylang WPGraphQL Extension

Posts/Post Polylang Language Feature

Constructing our GraphQL queries for translated posts

Get Next JS Headless WP Starter cloned and running locally

Next.js Internationalized Routing

Link to filter between languages

Apollo Client/GraphQL setup

Adding our GraphQL Queries

Multi-Lingual Posts on the Home Page

WPGraphQL/Polylang Single Post query

Dynamic Route Page and Single Post Query

Run the demo locally

Done!! Stoked! 🎉

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

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`