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

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

\n\n\n\n

Render Gutenberg Blocks as HTML
Use WPGraphQL Gutenberg

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

How WPGraphQL Gutenberg Works

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Setup

\n\n\n\n

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

\n\n\n\n

Here are the steps for getting set up:

\n\n\n\n

WordPress Backend Setup

\n\n\n\n

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

\n\n\n\n

Next.js App Setup

\n\n\n\n

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

\n\n\n\n

Render Blocks

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

SinglePost looks like this:

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Fix Internal Links

\n\n\n\n

Custom Server-side Block Parser

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Convert Anchor tags to Link Components

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Other Uses

\n\n\n\n

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

\n\n\n\n

Style Blocks

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Trade-off: Control vs. Ease of Implementation

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Wrapping Up

\n\n\n\n

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

\n\n\n\n

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

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

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Render Gutenberg Blocks as HTML
Use WPGraphQL Gutenberg

\n\n\n\n

We’ll discuss option #1 in this post.

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Render Gutenberg Blocks as HTML

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Fix Internal Links for Headless Gutenberg

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

A WordPress plugin that contains this code is available here.

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Style Blocks

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Use a Parser to Convert Some Blocks to Components

\n\n\n\n

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

\n\n\n\n

Example: Convert Anchor tags to Link Components

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

data-internal-link=\"true\"

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

With that in place, we can implement the parser.

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Other Uses

\n\n\n\n

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

\n\n\n\n

Trade-off: Control vs. Ease of Implementation

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Wrapping Up

\n\n\n\n

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

\n\n\n\n

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

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

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Introducing Atlas Content Modeler

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Content Modeler Real-World Usage

\n\n\n\n

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

\n\n\n\n

Project

\n\n\n\n

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

\n\n\n\n

Local Setup

\n\n\n\n

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

\n\n\n\n

Project Model Creation

\n\n\n\n

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

\n\n\n\n

The page now looks like this:

\n\n\n\n

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Custom Fields

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

Working with the Model in the WordPress Admin

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

Query for Data via WPGraphQL

\n\n\n\n

Here’s where things get cool! 😎

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Next.js App Example

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

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

\n\n\n\n

Where to Go from Here?

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

How Can I Help?

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Thanks for your interest in the project! 🙌

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

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Getting Started

\n\n\n\n

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

\n\n\n\n

Here are the steps for getting set up:

\n\n\n\n

WordPress Backend Setup

\n\n\n\n

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

\n\n\n\n

The CORS Settings page should now look like this:

\n\n\n\n

\n\n\n\n

Next.js App Setup

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Try it Out!

\n\n\n\n

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

\n\n\n\n

How it Works

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

A Note on Security

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Apollo Client Configuration

\n\n\n\n

Apollo Client is initialized in lib/apolloClient.ts.

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

`useAuth()` Hook

\n\n\n\n

Take a look at hooks/useAuth.tsx.

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

AuthContent & UnAuthContent Components

\n\n\n\n

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

\n\n\n\n

AuthContent

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

The logic works like this:

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

UnAuthContent

\n\n\n\n

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

\n\n\n\n

Features

\n\n\n\n

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

\n\n\n\n

Nav

\n\n\n\n

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

\n\n\n\n

Log In

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Log Out

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

New User Sign-up

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

The user flow goes like this:

\n\n\n\n

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

\n\n\n\n

This is the SignUpForm component that provides that functionality:

\n\n\n\n

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

\n\n\n\n

Set Password Link

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Set Password Form

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Password Strength Validation

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Password Resets

\n\n\n\n

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

\n\n\n\n

The password reset user flow goes like this:

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

User Profile Page

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Members Page

\n\n\n\n

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

\n\n\n\n

Create Post

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

But…why?

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Shared Cookies & Admin Access

\n\n\n\n

You might have noticed that:

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Control WordPress Admin Access

\n\n\n\n

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

\n\n\n\n

Headless WordPress Admin Access

\n\n\n\n

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

\n\n\n\n

CRUD Operations

\n\n\n\n

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

\n\n\n\n

How to Use in Production

\n\n\n\n

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

\n\n\n\n

WordPress Backend

\n\n\n\n

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

\n\n\n\n

Next.js Frontend

\n\n\n\n

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

\n\n\n\n

Wrapping Up

\n\n\n\n

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

\n\n\n\n

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

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

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Let’s roll! 🏎💨

\n\n\n\n

Getting Started

\n\n\n\n

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

\n\n\n\n

Here are the steps for getting set up:

\n\n\n\n

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

\n\n\n\n

How to Query for a Form

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

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

\n\n\n\n

Query for a Form in our App

\n\n\n\n

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

\n\n\n\n

Open up gatsby-node.js.

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Render the Form

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Render the Fields

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Managing our Form State

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Submitting Forms

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Error Handling

\n\n\n\n

Our Gatsby app handles two types of errors:

\n\n\n\n

Request or Server Errors

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Field Validation Errors

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

What’s Missing?

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Which Fields are Supported?

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Hide Unsupported Fields in the WordPress Admin

\n\n\n\n

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

\n\n\n\n

Gravity Forms Fields Allowlist

\n\n\n\n

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

\n\n\n\n

How Can I Use This in My Gatsby Projects?

\n\n\n\n

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

\n\n\n\n

Wrapping Up

\n\n\n\n

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

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

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Project Setup

\n\n\n\n

Before setting up cache rehydration, fulfill the following prerequisites:

\n\n\n\n

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

\n\n\n\n

Approach

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Install & Configure Apollo Client

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Let’s walk through each of those function definitions.

\n\n\n\n

createApolloClient()

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

initializeApollo()

\n\n\n\n

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

\n\n\n\n

addApolloState()

\n\n\n\n

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

\n\n\n\n

useApollo()

\n\n\n\n

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

\n\n\n\n

Render an ApolloProvider

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

How to Use in Page Components

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

SSR Page

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

CSR Page

\n\n\n\n

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

\n\n\n\n

Mixed SSG + CSR Page

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

How to Use this Code in Your Projects

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Wrapping Up

\n\n\n\n

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

\n\n\n\n

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

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

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

Set Up

\n\n\n\n

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

\n\n\n\n

Enable GraphQL Introspection

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

Initialize GraphQL Code Generator

\n\n\n\n

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

\n\n\n\n

What type of application are you building?

\n\n\n\n

Select Angular/React/any thing your heart desires.

\n\n\n\n

Where is your schema?

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

Where are your operations and fragments?

\n\n\n\n

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

\n\n\n\n

Pick plugins

\n\n\n\n

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

\n\n\n\n

Where to write the output

\n\n\n\n

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

\n\n\n\n

Do you want to generate an introspection file?

\n\n\n\n

Choose “No”.

\n\n\n\n

How to name the config file?

\n\n\n\n

Hit enter to accept the default codegen.yml filename.

\n\n\n\n

What script in package.json should run the codegen?

\n\n\n\n

Enter generate.

\n\n\n\n

The GraphQL Codegen CLI will:

\n\n\n\n

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

\n\n\n\n

The command line output should look something like this:

\n\n\n\n

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Generate Your Typings

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

How to Use the Generated Types

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

When to Generate Typings

\n\n\n\n

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

\n\n\n\n

Plugins & Integrations

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Wrapping Up

\n\n\n\n

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

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

Gravity Forms is one of the most popular premium form plugins for WordPress. It allows content creators to create a form, define which fields it should contain, render it to a page or post, and store form submissions. It also offers many extensions that provide additional features and integrations with many third-party services.

\n\n\n\n

In this post, we’ll learn how we can use WPGraphQL, and WPGraphQL for Gravity Forms on a headless WordPress backend to send and receive Gravity Forms data to/from a decoupled front-end React application.

\n\n\n\n

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

\n\n\n\n

Let’s roll! 🏎💨

\n\n\n\n

Getting Started

\n\n\n\n

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

\n\n\n\n

Here are the steps for getting set up:

\n\n\n\n

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

\n\n\n\n

How to Query for a Form

\n\n\n\n

The WPGraphQL for Gravity Forms plugin provides a gravityFormsForm query that we can use to query for data about our Gravity Forms forms. Here’s a simple example:

\n\n\n\n

query getForm {\n   gravityFormsForm(id: 5, idType: DATABASE_ID) {\n     formId\n     title\n     description\n     formFields(first: 500) {\n       nodes {\n         ... on TextField {\n           id\n           type\n           label\n         }\n         ... on SelectField {\n           id\n           type\n           label\n           choices {\n             text\n             value\n           }\n         }\n       }\n     }\n   }\n }

\n\n\n\n

We can test out this query right from the WordPress admin. Here’s how:

\n\n\n\n

Go to GraphQL > GraphiQL IDE.
Paste the query above into the left column, replacing id: 5 with the ID of the imported form.
Click the ▶ button to execute the query.
See the results returned in the right column.

\n\n\n\n

\n\n\n\n

Check out the WPGraphQL for Gravity Forms readme for more documentation on gravityFormsForm, as well as other queries and mutations the plugin offers.

\n\n\n\n

Query for a Form in our App

\n\n\n\n

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

\n\n\n\n

Open up the Next.js app in a code editor, and open pages/questionnaire.tsx. Notice that we’re exporting a getStaticProps() function from this file that calls an asynchronous getGravityForm() function, passing in a form ID and returning the form data that comes back. Next.js then handles passing that form data into the Questionnaire component.

\n\n\n\n

Go ahead and swap out the form ID being passed into getGravityForm() with the ID of the form you imported.

\n\n\n\n

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

\n\n\n\n

\n\n\n\n

But where’s all this form data-fetching magic happening? Let’s dig a bit deeper. Open up utilities/gravity-forms.tsx. You’ll see that we’re defining const GET_FORM, a gql tagged template literal containing our getForm GraphQL query. It accepts formId as an argument, then fetches the form with that ID.

\n\n\n\n

const GET_FORM = gql`\n  query getForm($formId: ID!) {\n    gravityFormsForm(id: $formId, idType: DATABASE_ID) {\n      formId\n      title\n      description\n      button {\n        text\n      }\n      confirmations {\n        isDefault\n        message\n      }\n      formFields(first: 500) {\n        nodes {\n          id\n          type\n          ... on AddressField {\n            ...AddressFieldFields\n          }\n          ... on CheckboxField {\n            ...CheckboxFieldFields\n          }\n          ... on DateField {\n            ...DateFieldFields\n          }\n          # etc.\n        }\n      }\n    }\n  }\n  ${ADDRESS_FIELD_FIELDS}\n  ${CHECKBOX_FIELD_FIELDS}\n  ${DATE_FIELD_FIELDS}\n  # etc.\n`;

\n\n\n\n

For the formFields > nodes union, we’re making use of GraphQL fragments. The fragments are imported from other field-specific files in the project and interpolated into our gql template literal using the ${ADDRESS_FIELD_FIELDS} syntax.

\n\n\n\n

These fields could have all been hardcoded in the gravity-forms.tsx file, but using GraphQL fragments allows us to co-locate the code that defines each field’s data requirements with the component responsible for rendering that field.

\n\n\n\n

Lastly, check out the getGravityForm() function definition. You can see that it calls Apollo Client’s client.query() function, passing to it the getForm query and the formId as a variable. After the request finishes, it returns the form data.

\n\n\n\n

Render the Form

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Render the Fields

\n\n\n\n

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

\n\n\n\n

Define their data requirements in a GraphQL fragment (which gets used in utilities/gravity-forms.tsx, as we saw earlier)
Define the field component, which accepts these props:
– field (the data about this field)
– fieldErrors (any errors specific to this field)
…and returns JSX for the field
Use the useGravityForm() custom React hook and
– Use its state object to get the current value for this field
– Call its dispatch function to update the field’s value in state

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Managing our Form State

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Submitting Forms

\n\n\n\n

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

\n\n\n\n

Error Handling

\n\n\n\n

Our front-end app handles two types of errors:

\n\n\n\n

Request or Server Errors

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Field Validation Errors

\n\n\n\n

What’s Missing?

\n\n\n\n

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

\n\n\n\n

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

\n\n\n\n

Which Fields are Supported?

\n\n\n\n

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

\n\n\n\n

Hide Unsupported Fields in the WordPress Admin

\n\n\n\n

Gravity Forms Fields Allowlist

\n\n\n\n

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

\n\n\n\n

How Can I Use This in My Projects?

\n\n\n\n

Copy and paste utilities/gravity-forms.tsx, hooks/useGravityForm.tsx, and all the components inside of /components into your codebase.
Mimic the code in pages/questionnaire.tsx in your app; call the getGravityForm(), passing in the ID of the form, and inside of the component that receives that form prop, render the <GravityForm form={form} /> component.
If you’re using TypeScript, set up GraphQL Code Generator to generate the TypeScript types stored in generated/graphql.ts and used throughout this app. A video and blog post are available that walk through this process.

\n\n\n\n

Wrapping Up

\n\n\n\n

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

\n"},{"__typename":"Post","id":"cG9zdDoxNzA=","uri":"/building-an-e-commerce-site-using-shopify-headless-wordpress-nextjs-and-chakra-ui-part-1-setup/","seo":{"__typename":"PostTypeSEO","readingTime":7,"title":"Building An E-Commerce Site Using Shopify, Headless WordPress, NextJS, and Chakra UI (Part 1: Setup) - WP Engine Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/f658bf43cf134f35589b4914311abd4f?s=96&d=mm&r=g"},"id":"dXNlcjoy","name":"Will Johnston","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"wjohnsto"}}}},"title0":"Building An E-Commerce Site Using Shopify, Headless WordPress, NextJS, and Chakra UI (Part 1: Setup)","content0":"\n

WordPress is not only a powerful publishing platform, it is also often used for e-commerce websites. With traditional WordPress you might use the WooCommerce plugin if you have a small e-commerce site, or you may use a Shopify plugin if you want to sell products you have listen through Shopify.

\n\n\n\n

When you move to using Headless WordPress you lose the functionality of the plugins, but all is not lost. This series of posts will walk you through using the Shopify API and Headless WordPress to build an e-commerce site that is lightning fast and uses the best tools for the right tasks. After you follow this series of posts you will have a functioning e-commerce site with the ability to tie posts in WordPress to products in your Shopify Store and vice versa.

\n\n\n\n

Depending upon your skill level, familiarity with Shopify’s GraphQL API, familiarity with NextJS/React/Chakra you may be able to skim through some of the posts in this series. I do encourage you to read through everything, as I will go into detail about everything included in the site you are building. In this post you will clone a starter site and I will walk you through the dependencies, setup, and some of the boilerplate code. This post assumes you have followed our tutorial on Setting Up WordPress As A Headless CMS and have a WordPress site and Shopify site already setup. This post also assumes you have the usual tools installed for working with NodeJS/NPM/code in general (i.e. git, nodejs, npm, an IDE/text editor, etc).

\n\n\n\n

Cloning The Boilerplate Site

\n\n\n\n

I have gone through the trouble of building out a starter site for you, so let’s start by cloning it:

\n\n\n\n

$ git clone https://github.com/wjohnsto/headless-shopify\n$ cd headless-shopify\n$ git checkout tags/v0.0.1

\n\n\n\n

Now you should have a directory on your computer called “headless-shopify.” It contains the boilerplate code for the website, let’s step into it:

\n\n\n\n

Walking Through The Boilerplate Site

\n\n\n\n

We are using NextJS for this site and if you are familiar with that then the layout of the files will make sense to you. We have the following top-level directories:

\n\n\n\n

components: Stores our functional React components to be used with the site
pages: Will contain our top-level pages (routes) for the site
public: Put static assets here, NextJS serves the site from this directory
styles: Contains any custom global styles. We are using Chakra UI, so we will not use this much

\n\n\n\n

There are also a number of files in the root project directory. You may already know what each of these files is, but for those that do not let’s take a look:

\n\n\n\n

.env.local.sample: This is a .env file that will store our environment variables. NextJS is setup to ensure any variables in this file end up on process.ENV at runtime.
.eslintrc.js: Contains configuration for ESLint, which helps keep annoying bugs out of our code and makes things consistent
.prettierrc.js: Contains our configuration for Prettier, which formats code and keeps it consistent
next-env.d.ts: An auto-generated file that keeps track of NextJS global typings
next.config.js: Configuration for NextJS. You can use this to add in Webpack plugins and configure your build
package.json: Contains our list of dependencies and scripts
README.md: Includes a little blurb about the project
tsconfig.json: Stores TypeScript configuration for compiling the TS files

\n\n\n\n

Overview Of Major Dependencies

\n\n\n\n

Before we go any further, let me list for you the large dependencies of our project and what we will be using them for:

\n\n\n\n

NextJS: A frontend and server-side framework used for building static and dynamic websites. We will use this for building out the site.
React: A frontend view library and dependency of NextJS
Chakra UI: A frontend UI library that contains utilities and components to make HTML layout easier. It works well with a React site.
@faustjs: A Headless WordPress library that makes data-fetching from WordPress and WPGraphQL easy
Apollo: An HTTP request library used to make API requests to WordPress and Shopify
TypeScript: A compile-to-JS language that allows us to write safer JS
ESLint: A linter for JS/TS that will keep our code consistent and keep some errors out
Prettier: A standard formatter for JS, the days of opinionated code formatting are over!

\n\n\n\n

There may be a few ancillary dependencies we use, but the above frameworks and libraries will be used to build out most of our site.

\n\n\n\n

Setting Up Your Site To Point To WordPress

\n\n\n\n

Go ahead and copy the .env.local.sample file into a .env.local file and change your NEXT_PUBLIC_WORDPRESS_URL to point to your local WordPress site. For example, I am using Local and my NEXT_PUBLIC_WORDPRESS_URL looks like this:

\n\n\n\n

NEXT_PUBLIC_WORDPRESS_URL=http://wptest.local/

\n\n\n\n

After you set this variable up you will be able to run npm run dev and see the default site. You will get a blank page until you go into your wp-admin and edit a couple posts to add them to a Featured category. Once you do this you should see some posts appear on your home page when you run npm run dev and visit http://localhost:3000.

\n\n\n\n

Boilerplate Components And Pages

\n\n\n\n

I have provided you with an index/home page as well as two components to get you started. I have also taken the liberty of overwriting the default NextJS pages/_app.tsx to include the Chakra UI provider and the @wpengine/headless providers. These components are necessary in order to work with the two libraries.

\n\n\n\n

The Index Page (i.e. `pages/index.tsx`)

\n\n\n\n

Looking at our index page you will see that we are making a GraphQL query to fetch posts in the featured category:

\n\n\n\n

const featuredPostsQuery = gql`\n  query {\n    posts(where: { categoryName: \"featured\" }) {\n      nodes {\n        title\n        excerpt\n        slug\n        tags(where: { search: \"collection-\" }) {\n          nodes {\n            name\n          }\n        }\n      }\n    }\n  }\n`;

\n\n\n\n

You will notice we use the above query and @apollo/client to make a request to WordPress to get our list of featured posts. Our Home component does this as follows:

\n\n\n\n

function Home() {\n  const { data } = useQuery<WPGraphQL.GetPostsQuery>(featuredPostsQuery);\n\n  return (\n    <Layout>\n      <Stack spacing={8}>\n        {data?.posts.nodes.map(({ slug, title, excerpt}) => (\n          <PostBox key={slug} slug={slug} title={title} content={excerpt} />\n        ))}\n      </Stack>\n    </Layout>\n  );\n}

\n\n\n\n

We are using a Chakra UI <Stack /> component to layout our list of posts. We are also using two custom components: <Layout /> and <PostBox /> which I will cover in a moment. The Home component iterates over our featured posts and shows each post in a stack.

\n\n\n\n

We could be done here, but since this is not only a Headless WordPress site but also an e-commerce site we are focused on speed. There is no reason why we shouldn’t statically generate the index page, so if you look towards the bottom of the file you will see a getStaticProps function:

\n\n\n\n

export async function getStaticProps(ctx: GetStaticPropsContext) {\n  const client = getApolloClient(ctx);\n  await client.query<{\n    posts: WPGraphQL.RootQuery['posts'];\n  }>({\n    query: featuredPostsQuery,\n  });\n\n  return getNextStaticProps(ctx);\n}

\n\n\n\n

In this function we make sure we call to get our featured posts, and use the same query we will use in the Home component. The @wpengine/headless library will do the work of extracting the Apollo client cache, putting it on props, and restoring it client-side so that we do not end up making a client-side request for the posts.

\n\n\n\n

The Layout And PostBox Components

\n\n\n\n

If you look at the <Layout /> component in components/Layout.tsx you will see a basic functional React component that simply sets up our favicon and puts its children in a Chakra UI <Container />. We will be using this component for every page we build to maintain consistency.

\n\n\n\n

In components/PostBox.tsx you will find a functional component that renders our post inside of a Chakra UI <LinkBox />. The LinkBox is a crafty component that allows us to semantically wrap our post in a link. The rest of this component is pretty straight forward, it expects some WordPress post attributes and renders the title and content passed in into a box.

\n\n\n\n

Wrapping Up

\n\n\n\n

That’s the basic overview of our boilerplate site. If you have configured your environment variable and added the featured category to some WordPress posts you should be able to run npm run dev and see your list of featured posts at http://localhost:3000. This series will gradually build off this boilerplate and in the end you will have an e-commerce and Headless WordPress site using Shopify! We will come back and update this post once Part 2 is live but in the mean time check out some of the other posts we have or have fun digging into some of the dependencies we will be using for this series!

\n"},{"__typename":"Post","id":"cG9zdDoxNjc=","uri":"/state-of-headless-development/","seo":{"__typename":"PostTypeSEO","readingTime":1,"title":"State of Headless Development - WP Engine Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/5f44a3b86a7551f4f371ff127c64541f?s=96&d=mm&r=g"},"id":"dXNlcjo0","name":"Nate Archer","description":null,"seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":""}}}},"title0":"State of Headless Development","content0":"\n

With so many businesses still using a traditional CMS, headless development remains nascent. Yet, the need for omnichannel content delivery has increased tenfold. Content managers and developers seek to close the gap between writing and deploying beautiful content, wanting ease of use and flexibility.

\n\n\n\n

Therefore, as more players enter the headless development space, it’s useful for you to know who’s who. WPEngine blog writer Abe Selig, with the help of research firm Vanson Bourne, has created a guide for the current state of headless. Naturally, it’s called The State Of Headless: A Global Research Report.

\n\n\n\n

We encourage you to read the blog in its entirety, but here are some key takeaways:

\n\n\n\n

TL;DR

\n\n\n\n

Headless technology has thus far seen the most adoption from enterprise level users. Over 64% of users who responded to the research said they use some form of headless.
92% of all respondents believe that headless delivers a more consistent content experience for end-users.
Most concerns around headless revolve around the skill needed for set up and cost.
Users who choose headless technology do so because of the performance benefits, eCommerce, and to deliver content across several IoT devices.

\n\n\n\n

Want to know more? Give The State Of Headless: A Global Research Report a read.

\n"},{"__typename":"Post","id":"cG9zdDo4Mw==","uri":"/custom-content-types-in-headless-wordpress/","seo":{"__typename":"PostTypeSEO","readingTime":6,"title":"Custom Content Types in Headless WordPress - WP Engine Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/7989ef6362a23b4584b47a77887549e6?s=96&d=mm&r=g"},"id":"dXNlcjox","name":"Matt Landers","description":null,"seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"matt_landers"}}}},"title0":"Custom Content Types in Headless WordPress","content0":"\n

When you build a headless site, you are dependent on an API to provide structured content to the frontend from the CMS. The frontend takes the content and decides how to display it to the user. But how the frontend shows that content comes in different forms. Content producers used to render posts in HTML because they need more control over how the content looks. But for other content types, such as employees on a team page, you should structure content. The frontend takes the structured data and renders it to the user according to the design.

\n\n\n\n

All headless CMSs allow you to create structured data via custom content types, but how do we do this in WordPress? Through the power of the plugin ecosystem, of course! With a few plugins, we can create a good experience for the content producer to enter structured data. The plugins that we’ll need are:

\n\n\n\n

WPGraphQL
Custom Post Types UI
CPT extension for WPGraphQL
Advanced Custom Fields
ACF extension for WPGraphQL

\n\n\n\n

With these plugins, we can create a UI in WordPress that looks like this:

\n\n\n\n

\n\n\n\n

Let’s walk through the steps needed to create this UI.

\n\n\n\n

Create the Custom Post Type

\n\n\n\n

The first thing we need to do is create a custom post type. We can do this with the CPT UI plugin. Click CPT UI in the menu. The following interface appears:

\n\n\n\n

\n\n\n\n

For our team members’ post type, we can use “teammembers” for Post Type Slug. “Team Members” for the plural label and “Team Member” for the singular labels. Add the labels in the WP admin in the navigation bar and editor for team members.

\n\n\n\n

Scroll down to the bottom of the page, and you’ll see a section for WPGraphQL that looks like this:

\n\n\n\n

\n\n\n\n

We need to tell WPGraphQL what to call the entity in the schema for plural and singular. Use this syntax for your queries. For Single Name, use “teammember”, and for Plural Name, use “teammembers”.

\n\n\n\n

To put the finishing touches on our editing experience, turn off Featured Image and Editor.

\n\n\n\n

Scroll up just a bit, and you’ll see a list of supported items.
Unselect Editor and Featured Image.

\n\n\n\n

\n\n\n\n

Now, you can click Save Post Type. At this point, you’ll see “Team Members” in the side navigation. If you click it and add a new team member, you’ll only see the title in the editor. We need more than a title, so let’s add custom fields to the post type.

\n\n\n\n

Add Custom Fields

\n\n\n\n

In the side navigation, click Custom Fields. A list of field groups appears. Click Add New to start creating a new custom field group.

\n\n\n\n

First, we need to give the field group a name. This can be whatever will help you identify the field group. Let’s call it “Team Member Fields.” Next, we need to let ACF know where we want to apply these fields. We can do this in the Location section. The field group should not show up on every post because it is specific to team members. We only want to show the field group when the post type is equal to “Team Member.”

\n\n\n\n

\n\n\n\n

Now that we set the location, we need to add custom fields to the field group. Click the + Add Field button. The following screen appears:

\n\n\n\n

\n\n\n\n

Let’s add a field for a description of the team member. Enter “Bio” as the Field Label, and the Field Name will be auto-populated with “Bio”. The Field Name is what we will use in our GraphQL queries.

\n\n\n\n

A bio will likely be more than one line, so let’s change the Field Type to “Text Area.” The Field Type determines how the user will enter the data, and the Text Area will give the user a multi-line input box.

\n\n\n\n

There are other options like required and instructions that you can fill out, but make sure that Show in GraphQL is selected. If we don’t turn that on, we won’t query the field from GraphQL.

\n\n\n\n

There are other options like required and instructions that you can fill out as well, but the one option we need to make sure is slected is “Show in GraphQL”. If we don’t turn that on, we won’t be able to query the field from GraphQL.

\n\n\n\n

We’re going to use Title for the name field. That way, when we view the list of Team Members, we will see them listed by name. You could also create a name field, but it would be redundant for the user that enters the team members.

\n\n\n\n

Once you’ve added all the fields you want on a team member, please scroll down to the bottom of the page and make sure you have Show in GraphQL selected and provide a GraphQL Field Name, the name used when we query team members. Let’s name it “acfTeamMembers”.

\n\n\n\n

\n\n\n\n

Finally, scroll back to the top of the page, and click Publish. Once published, click on Team Members in the navigation and add a new team member. You should see the title field and all the custom fields you added. ????

\n\n\n\n

Next, let’s query our custom content type with WPGraphQL!

\n\n\n\n

Query Custom Content Types

\n\n\n\n

At this point, you should have a custom content type for team members in WP admin. Make sure you add a few team members before going any further to see the GraphQL query results, then open the GraphiQL IDE via the top navigation.

\n\n\n\n

\n\n\n\n

To build the query, use the schema explorer on the UI’s left side and find the “teammembers” entity. Expand it and select the fields you want to query. GraphiQL will modify the query in the editor to match what you choose. Run the query by pressing the play button above the editor. Here’s an example query, but it may be different depending on the fields you added.

\n\n\n\n

{\n  teammembers {\n    nodes {\n      title\n      acfTeamMembers {\n        bio\n        linkedin\n        twitter\n      }\n    }\n  }\n}\n

\n\n\n\n

And that’s it! Now, you can query team members from anywhere you need the data and get back structured data just like you defined it.

\n"},{"__typename":"Post","id":"cG9zdDoxMzM=","uri":"/headless-wordpress-with-vue-and-nuxt-js/","seo":{"__typename":"PostTypeSEO","readingTime":10,"title":"Headless WordPress With Vue and Nuxt.js - WP Engine Developers"},"author":{"__typename":"NodeWithAuthorToUserConnectionEdge","node":{"__typename":"User","avatar0":{"__typename":"Avatar","url":"https://secure.gravatar.com/avatar/f658bf43cf134f35589b4914311abd4f?s=96&d=mm&r=g"},"id":"dXNlcjoy","name":"Will Johnston","description":"---\r\ntitle: Sr. Staff Developer Advocate\r\n---","seo":{"__typename":"SEOUser","social":{"__typename":"SEOUserSocial","twitter":"wjohnsto"}}}},"title0":"Headless WordPress With Vue and Nuxt.js","content0":"\n

If you have not already read our post on Headless WordPress With Next.js I encourage you to go through it if you are interested in learning how to create a Headless WordPress site with React Next.js. This post is going to cover a similar topic, but with Vue and Nuxt.js instead.

\n\n\n\n

What Is Nuxt.js?

\n\n\n\n

Nuxt.js (or simply Nuxt) is a server-side framework for writing frontend applications using Vue. Vue is a frontend framework similar to Angular or React… kinda. There are plenty of comparison articles on React versus Vue, and most will point out that Vue is more a framework while React is a library. Let’s not get into that for this post. For this post, we will assume Vue and React offer essentially the same thing for frontend developers and work with their respective Nuxt and Next server counterparts.

\n\n\n\n

You can think of Nuxt as Next but for Vue instead of React. So if you are looking to write a Headless WordPress site and want to use Vue, Nuxt may be an excellent option for you to use as your server-side framework. It supports Server-Side Rendering and Static Site Generation similar to Next and is generally an opinionated framework that helps you build a frontend website. Before we dive into Nuxt let’s first discuss how to setup WordPress for headless.

\n\n\n\n

Setting Up WordPress For Headless

\n\n\n\n

If you haven’t already, check out our post about setting up WordPress for headless. For this post, you will need to install and configure the following plugins (outlined in the post linked above):

\n\n\n\n

Make sure you follow the instructions in the post for configuring WPEngine Headless. In the WPEngine Headless settings (found in Settings > Headless), set Front-end site URL to http://localhost:3000/. This will eventually be the URL that serves where our frontend site.

\n\n\n\n

Creating The Nuxt Site

\n\n\n\n

Now that you have your WordPress site hooked up, let’s dive into creating our Nuxt app. We will be following the create-nuxt-app installation instructions from the Nuxt documentation for the most part, with some configuration. You can start by opening a terminal to where you want to create your app and running the following:

\n\n\n\n

$ npx create-nuxt-app <project-name>

\n\n\n\n

For this project, I will use the name nuxt-headless-wp, but you can use whatever name you want. create-nuxt-app is going to ask you some configuration questions, such as:

\n\n\n\n

create-nuxt-app v3.5.2\n✨  Generating Nuxt.js project in nuxt-headless-wp\n? Project name: nuxt-headless-wp\n? Programming language: TypeScript\n? Package manager: Npm\n? UI framework: Bootstrap Vue\n? Nuxt.js modules: (Press <space> to select, <a> to toggle all, <i> to invert selection)\n? Linting tools: ESLint, Prettier\n? Testing framework: Jest\n? Rendering mode: Universal (SSR / SSG)\n? Deployment target: Server (Node.js hosting)\n? Development tools: (Press <space> to select, <a> to toggle all, <i> to invert selection)\n? Continuous integration: None\n? Version control system: Git

\n\n\n\n

After your Nuxt app is generated you will get instructions on how to run your site, which should look something like the following:

\n\n\n\n

$ cd nuxt-headless-wp\n$ npm run dev

\n\n\n\n

If you don’t get any errors, your site should be running on http://localhost:3000/. We’re done…

\n\n\n\n

Not! Now is when things get interesting.

\n\n\n\n

Building Pages For The Blog

\n\n\n\n

We’re going to keep with a simple UI using only Bootstrap CSS classes. Let’s first scaffold out our HTML with some dummy data and style it a little before adding in data from our WordPress CMS. We will want the index page to show a list of posts and let you navigate to an individual post. Let’s start with the index page.

\n\n\n\n

Showing A List Of Posts

\n\n\n\n

In pages/index.vue, remove all of the styles in the <style></style> tags. We won’t be needing this. Next, let’s add some dummy data in the TS area of our index.vue. Add the following script:

\n\n\n\n

import Vue from 'vue'\n\nexport default Vue.extend({\n  computed: {\n    posts() {\n      return [\n        {\n          title: 'Test Post',\n          slug: 'test-post',\n          content: '<p>This is a test post</p>',\n          excerpt: '<p>This is a test post</p>',\n        },\n      ]\n    },\n    pageInfo() {\n      return {\n        endCursor: '',\n        hasNextPage: false,\n        hasPreviousPage: false,\n        startCursor: '',\n      }\n    },\n  },\n})

\n\n\n\n

The code above sets up two computed properties with default values for a list of posts and page information. We are using computed properties because later, we will populate these with values from a Vuex store.

\n\n\n\n

Now that we have some sample data let’s build out our list of posts. Use the following template:

\n\n\n\n

<template>\n  <div class=\"container\">\n    <div>\n      <h1 class=\"text-center\">Nuxt Headless WordPress Demo</h1>\n      <div class=\"container py-4 posts\">\n        <div class=\"row\">\n          <post-card v-for=\"post in posts\" :key=\"post.slug\" :post=\"post\" />\n          <div class=\"d-flex w-100\">\n            <div class=\"ml-auto\" v-if=\"pageInfo.hasNextPage\">\n              <NuxtLink :to=\"{ query: { after: pageInfo.endCursor } }\"\n                ><span>Next Page</span></NuxtLink\n              >\n            </div>\n          </div>\n        </div>\n      </div>\n    </div>\n  </div>\n</template>

\n\n\n\n

This code is going to iterate through our posts computed property and render a post-card for each post. It will also show a link to view the next page of posts if there is one. You might be wondering what post-card is. We need to create our post-card component so that we can show our posts as cards. Add a components/PostCard.vue and put the following code in it:

\n\n\n\n

<template>\n  <article class=\"col-12 py-5\">\n    <div class=\"card shadow\">\n      <div class=\"card-body\">\n        <h5 class=\"card-title\">\n          <NuxtLink :to=\"{ name: 'slug', params: { slug: post.slug } }\">{{\n            post.title\n          }}</NuxtLink>\n        </h5>\n        <!-- eslint-disable-next-line vue/no-v-html -->\n        <div class=\"card-text\" v-html=\"post.excerpt\"></div>\n      </div>\n    </div>\n  </article>\n</template>\n\n<script lang=\"ts\">\nimport { PropsDefinition } from 'vue/types/options'\nimport { Post } from '~/store/posts'\n\nexport default {\n  props: ['post'] as PropsDefinition<{ post: Post }>,\n}\n</script>

\n\n\n\n

The PostCard component expects a post prop and will render the post title and excerpt in a Bootstrap card. It will also link to what will eventually be our single post page. Before you continue, run your app and make sure you see the test post.

\n\n\n\n

Showing A Single Post

\n\n\n\n

Now that we have our list of posts displaying let’s add a single post page. If you look at the PostCard.vue component, you will see that we link to a slug page that takes in a slug parameter. Create a pages/_slug.vue that will receive the slug URL parameter and use it to display a post. Put the following code into the _slug.vue page:

\n\n\n\n

<template>\n  <div class=\"container\">\n    <h1 class=\"text-center\">{{ post.title }}</h1>\n    <!-- eslint-disable-next-line vue/no-v-html -->\n    <article class=\"py-5\" v-html=\"post.content\"></article>\n  </div>\n</template>\n\n<script lang=\"ts\">\nimport Vue from 'vue'\n\nexport default Vue.extend({\n  computed: {\n    post() {\n      return {\n        title: 'Test Post',\n        slug: 'test-post',\n        content: '<p>This is a test post</p>',\n        excerpt: '<p>This is a test post</p>',\n      }\n    },\n  },\n})\n</script>\n

\n\n\n\n

When you run your app, you will be able to navigate from the list of posts to a single post. Now we have to actually populate our list of posts with data from our WordPress site.

\n\n\n\n

Building The Posts Store

\n\n\n\n

To get data from WordPress, we need a store, but we need to install some dependencies. Run the following commands from the root directory of your project:

\n\n\n\n

$ npm i apollo-boost graphql isomorphic-fetch vue-apollo\n$ npm i -D @types/isomorphic-fetch

\n\n\n\n

This will install the dependencies we need to call our WordPress GraphQL API and retrieve our lists of posts and individual posts. The next thing we need to do is set up a store for our posts. Add a store/posts.ts file. This file is going to have a number of things:

\n\n\n\n

TypeScript interfaces for our data
GQL query strings
Apollo client setup
State definition
Mutation methods
Action methods

\n\n\n\n

Let’s step through this 1-by-1. We’re going to need to import the following dependencies at the top of our posts.ts file:

\n\n\n\n

import { ActionContext } from 'vuex'\nimport ApolloClient, { gql } from 'apollo-boost'\nimport fetch from 'isomorphic-fetch'

\n\n\n\n

Next, let’s create our TypeScript interfaces, so we know the shape of the data we’re trying to fetch. In your posts.ts file put the following interfaces:

\n\n\n\n

export interface Post {\n  id: string\n  slug: string\n  title: string\n  content: string\n  excerpt: string\n  uri: string\n  status: string\n}\n\nexport interface PageInfo {\n  endCursor: string\n  hasNextPage: boolean\n  hasPreviousPage: boolean\n  startCursor: string\n}\n\nexport interface PostsState {\n  nodes: Post[]\n  pageInfo: PageInfo\n  post: Post\n}

\n\n\n\n

Now, let’s use the gql library to format our GQL queries. Earlier, we installed the WPGraphQL plugin for WordPress, so we need to use its schema. Put the following queries in your posts.ts file:

\n\n\n\n

const postsQuery = gql`\n  fragment pageInfoData on WPPageInfo {\n    endCursor\n    hasNextPage\n    hasPreviousPage\n    startCursor\n  }\n  fragment listPostData on Post {\n    id\n    slug\n    title\n    content\n    excerpt\n    uri\n    status\n  }\n  query GetPosts(\n    $where: RootQueryToPostConnectionWhereArgs\n    $after: String\n    $before: String\n    $first: Int\n    $last: Int\n  ) {\n    posts(\n      where: $where\n      after: $after\n      before: $before\n      first: $first\n      last: $last\n    ) {\n      pageInfo {\n        ...pageInfoData\n      }\n      nodes {\n        ...listPostData\n      }\n    }\n  }\n`\n\nconst postQuery = gql`\n  fragment postData on Post {\n    id\n    slug\n    title\n    content\n    uri\n    status\n  }\n  fragment pageData on Page {\n    id\n    slug\n    title\n    content\n    uri\n    status\n  }\n  query GetContentNode($id: ID!) {\n    contentNode(id: $id, idType: URI) {\n      ... on Post {\n        ...postData\n      }\n      ... on Page {\n        ...pageData\n      }\n    }\n  }\n`

\n\n\n\n

Use the first query to get a list of posts and the second an individual post. Note that the fields in our query match the fields in the TypeScript interfaces.

\n\n\n\n

Next, let’s set up our Apollo client. I am going to use a demo WordPress site, but you can use your own:

\n\n\n\n

const client = new ApolloClient({\n  uri: `https://headlessfw.wpengine.com/graphql`,\n  fetch,\n})

\n\n\n\n

Now we need to define our state:

\n\n\n\n

export function state(): PostsState {\n  return {\n    nodes: [],\n    pageInfo: {\n      endCursor: '',\n      hasNextPage: false,\n      hasPreviousPage: false,\n      startCursor: '',\n    },\n    post: {\n      id: '',\n      slug: '',\n      title: '',\n      content: '',\n      excerpt: '',\n      uri: '',\n      status: '',\n    },\n  }\n}

\n\n\n\n

The last piece of this puzzle is to create the functions that will fetch our data and provide it to the view. Create the following mutations:

\n\n\n\n

export const mutations = {\n  setPosts(state: PostsState, posts: any[]) {\n    state.nodes = posts\n  },\n  setPost(state: PostsState, post: any) {\n    state.post = post\n  },\n  setPageInfo(state: PostsState, pageInfo: any) {\n    state.pageInfo = pageInfo\n  },\n}

\n\n\n\n

These mutations will let us set a state and provide a list of posts, page information, and an individual post. Next, create the following actions:

\n\n\n\n

\nexport const actions = {\n  async getPosts(\n    { commit }: ActionContext<PostsState, PostsState>,\n    variables: any\n  ) {\n    const result = await client.query({\n      query: postsQuery,\n      variables,\n    })\n\n    const { nodes, pageInfo } = result.data?.posts\n\n    commit('setPosts', nodes)\n    commit('setPageInfo', pageInfo)\n  },\n  async getPost(\n    { commit }: ActionContext<PostsState, PostsState>,\n    slug: string\n  ) {\n    const result = await client.query({\n      query: postQuery,\n      variables: {\n        id: slug,\n      },\n    })\n\n    const post = result.data?.contentNode\n    commit('setPost', post)\n  },\n}\n

\n\n\n\n

We have two actions: getting the list of posts and the other for getting an individual post. Both use our GQL queries and the Apollo client to make requests to our WordPress site for data, and then they commit the data to the state by calling the mutations. Now we have our store, the last piece we need is to wire it up to our views.

\n\n\n\n

Wiring Up The Data

\n\n\n\n

To wire up the state from our store to our view, we will need to modify our index.vue and _slug.vue pages. Modify the script in the index.vue page to look like the following:

\n\n\n\n

import Vue from 'vue'\nimport { PostsState } from '~/store/posts'\n\nconst pageCount = 5\n\nexport default Vue.extend({\n  computed: {\n    posts() {\n      return (this.$store.state.posts as PostsState).nodes\n    },\n    pageInfo() {\n      return (this.$store.state.posts as PostsState).pageInfo\n    },\n  },\n  watch: {\n    async $route() {\n      await this.$nuxt.refresh()\n      window.scrollTo(0, 0)\n    },\n  },\n  async asyncData({ store, query }) {\n    await store.dispatch('posts/getPosts', {\n      after: query.after,\n      before: query.before,\n      first: query.before ? undefined : pageCount,\n      last: query.before ? pageCount : undefined,\n    })\n  },\n})

\n\n\n\n

This accomplishes a few goals. First, it changes our computed properties from being hardcoded to using the posts state values. Second, it sets up a $route watcher that will refresh our data when the route changes and scroll to the top of the page. This is used for pagination (note we are using a pageCount of 10). The next page will create a query string with the appropriate parameters and refresh the data when you go to the next page. The last thing this code does is implement the asyncData hook to dispatch the posts/getPosts action, retrieve the list of posts, and then set them on the state. Now let’s modify the _slug.vue to have the following script:

\n\n\n\n

import Vue from 'vue'\n\nexport default Vue.extend({\n  computed: {\n    post() {\n      return this.$store.state.posts.post\n    },\n  },\n  async asyncData({ store, params }) {\n    await store.dispatch('posts/getPost', params.slug)\n  },\n})

\n\n\n\n

This is much more straightforward. All we need to do in the _slug.vue page is dispatch the action to get a single post.

\n\n\n\n

There you have it; you have successfully set up a Headless WordPress blog using Vue and Nuxt! Now when you run your site, you should see a paginated list of posts. If you have more than 10 posts, you will be able to page through them. Click on the title of a post, that title will take you to the individual page for that post, where you see all of the content.

\n\n\n\n

When you are still struggling to get your site setup, check out the code for this post. If you haven’t already and are interested, be sure to check out our post on Headless WordPress Using NextJS.

\n"}]},"seo":{"schema":{"siteUrl":"https://developers.wpengine.com","__typename":"SEOSchema","companyLogo":{"__typename":"MediaItem","id":"cG9zdDoxNjg=","altText":""},"siteName":"WP Engine Developers"},"__typename":"SEOConfig"}},"selections":[[["0-1-2","youtubeVideos0"],["3-1-4","posts0"],["5-6-7","avatar0"],["8-6-9","title0"],["3-10-4","posts1"],["11-12-13","post0"],["14-6-9","content0"],["15-16-17","headlessWordPressPlugins0"],["0-10-2","youtubeVideos1"],["11-18-13","post1"],["11-19-13","post2"],["11-20-13","post3"],["11-21-13","post4"],["11-22-13","post5"],["11-23-13","post6"],["11-24-13","post7"],["11-25-13","post8"],["11-26-13","post9"],["3-27-4","posts2"],["11-28-13","post10"],["11-29-13","post11"],["11-30-13","post12"],["11-31-13","post13"],["11-32-13","post14"],["11-33-13","post15"],["11-34-13","post16"],["11-35-13","post17"]],[["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}",10],["post",11],["{\"id\":\"gutenberg-in-headless-wordpress-wpgraphql-gutenberg\",\"idType\":\"SLUG\"}",12],["{\"id\":\"ID!\",\"idType\":\"PostIdType\",\"asPreview\":\"Boolean\"}",13],["content",14],["headlessWordPressPlugins",15],["{\"first\":500}",16],["{\"first\":\"Int\",\"last\":\"Int\",\"after\":\"String\",\"before\":\"String\",\"where\":\"RootQueryToHeadlessWordPressPluginConnectionWhereArgs\"}",17],["{\"id\":\"what-is-atlas-content-modeler\",\"idType\":\"SLUG\"}",18],["{\"id\":\"gutenberg-in-headless-wordpress-render-blocks-as-html\",\"idType\":\"SLUG\"}",19],["{\"id\":\"headless-wordpress-with-vue-and-nuxt-js\",\"idType\":\"SLUG\"}",20],["{\"id\":\"gravity-forms-in-headless-wordpress-gatsby\",\"idType\":\"SLUG\"}",21],["{\"id\":\"custom-content-types-in-headless-wordpress\",\"idType\":\"SLUG\"}",22],["{\"id\":\"graphql-code-generator-for-wpgraphql\",\"idType\":\"SLUG\"}",23],["{\"id\":\"work-with-gravity-forms-in-headless-wordpress\",\"idType\":\"SLUG\"}",24],["{\"id\":\"headless-wordpress-authentication-native-cookies\",\"idType\":\"SLUG\"}",25],["{\"id\":\"building-an-e-commerce-site-using-shopify-headless-wordpress-nextjs-and-chakra-ui-part-1-setup\",\"idType\":\"SLUG\"}",26],["{\"first\":12,\"after\":\"YXJyYXljb25uZWN0aW9uOjEzMw==\"}",27],["{\"id\":\"apollo-client-cache-rehydration-in-next-js\",\"idType\":\"SLUG\"}",28],["{\"id\":\"state-of-headless-development\",\"idType\":\"SLUG\"}",29],["{\"id\":\"set-up-wordpress-as-a-headless-cms\",\"idType\":\"SLUG\"}",30],["{\"id\":\"previews-in-headless-wordpress-using-nextjs\",\"idType\":\"SLUG\"}",31],["{\"id\":\"introduction-to-graphql-in-wordpress\",\"idType\":\"SLUG\"}",32],["{\"id\":\"what-is-headless\",\"idType\":\"SLUG\"}",33],["{\"id\":\"introduction-to-the-wordpress-rest-api\",\"idType\":\"SLUG\"}",34],["{\"id\":\"xmlrpc.php\",\"idType\":\"SLUG\"}",35]],[[0,1],[3,2],[5,0],[8,0],[11,17],[14,0],[15,0]],"v0"]}

How WPGraphQL Gutenberg Works

Setup

WordPress Backend Setup

Next.js App Setup

Render Blocks

Fix Internal Links

Custom Server-side Block Parser

Convert Anchor tags to Link Components

Other Uses

Style Blocks

Trade-off: Control vs. Ease of Implementation

Wrapping Up

Render Gutenberg Blocks as HTML

Fix Internal Links for Headless Gutenberg

Style Blocks

Use a Parser to Convert Some Blocks to Components

Example: Convert Anchor tags to Link Components

Other Uses

Trade-off: Control vs. Ease of Implementation

Wrapping Up

Introducing Atlas Content Modeler

Content Modeler Real-World Usage

Local Setup

Project Model Creation

Custom Fields

Working with the Model in the WordPress Admin

Query for Data via WPGraphQL

Next.js App Example

Where to Go from Here?

How Can I Help?

Getting Started

WordPress Backend Setup

Next.js App Setup

Try it Out!

How it Works

A Note on Security

Apollo Client Configuration

useAuth() Hook

AuthContent & UnAuthContent Components

AuthContent

UnAuthContent

Features

Nav

Log In

Log Out

New User Sign-up

Set Password Link

Set Password Form

Password Strength Validation

Password Resets

User Profile Page

Members Page

Create Post

But…why?

Shared Cookies & Admin Access

Control WordPress Admin Access

CRUD Operations

How to Use in Production

WordPress Backend

Next.js Frontend

Wrapping Up

Getting Started

How to Query for a Form

Query for a Form in our App

Render the Form

Render the Fields

Managing our Form State

Submitting Forms

Error Handling

Request or Server Errors

Field Validation Errors

What’s Missing?

Which Fields are Supported?

Hide Unsupported Fields in the WordPress Admin

How Can I Use This in My Gatsby Projects?

Wrapping Up

Project Setup

Approach

Install & Configure Apollo Client

createApolloClient()

`useAuth()` Hook

The Index Page (i.e. `pages/index.tsx`)