DEV Community: Fran Agulto

Using Fragments with WPGraphQL in Faust.js

Fran Agulto — Thu, 20 Jul 2023 21:08:07 +0000

In WPGraphQL, fragments are a feature of GraphQL in the GraphQL query languagethat allows you to define reusable selections of fields. Fragments allow you to group fields together and give them a name, which can then be used in multiple queries or mutations.

In this article, I will explain what they provide and how to use them in Faust.js. Even though we’re using Faust.js, you should be able to transfer this knowledge to any other using WPGraphQL.

Getting Started

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

Steps for Local Development Set-up

WordPress Setup:

Set up a WordPress site on local, WP Engine, or any host of your choice

Set up a WordPress site on local, WP Engine, or any host of your choice
Install and activate the WPGraphQL plugin
Install and activate the Faust.js plugin
Install and activate the Advanced Custom Fields plugin
Install and activate the WPGraphQL For Advanced custom fields plugin

Faust.js Setup

Please follow the instructions to set up Faust.js in the quickstart portion of the docs here.

The Benefits of Using Fragments

Code Reusability: Fragments enable you to define a set of fields once and reuse them across different queries or mutations. This helps in reducing code duplication and promotes a modular approach to defining GraphQL operations.

Query Organization: Fragments help organize complex queries by breaking them into smaller, more manageable parts. You can efficiently compose queries and maintain a clear structure by defining fragments for specific data structures or entities.

Readability and Maintainability: Fragments make GraphQL queries more readable and understandable. Separating the fields into reusable fragments makes it easier to grasp the structure of the data being queried. Additionally, when changes are required, you can update the fragment definition, and all the queries using that fragment will be automatically updated.

How to Create and Implement Fragments for Your WPGraphQL Queries

Now that we went over the benefits of using fragments, let’s create some.

In this example, I have a custom post type called Movies with the fields title, id, slug and uri that we want to request.

{
  movies {
    nodes {
      title
      id
      slug
      uri
    }
  }
}

The above code is a WPGraphQL query with no fragments.

This is what it would look like if we made a fragment for the above query:

{
  movies {
    nodes {
      ...MovieFragment
    }
  }
}

fragment MovieFragment on Movie {
  title
  id
  slug
  uri
}

Let’s break down how we created a fragment for our query.

Once we know what fields we want to pull out from our Movies custom post type, we start making our fragment with the keyword fragment followed by the name we choose, in this case, we call it MovieFragment.

The on Movie clause specifies this fragment is applicable to the Movie object type. When WPGraphQL returns a node of type Movie, it uses this fragment to determine what fields to return on the result.

Inside the fragment, there are several fields (title, id, slug, uri) that correspond to the fields of the Movie type.

Lastly, we take our fragment named MovieFragment and insert it into the main query block right under the nodes that the original query had with the fields instead of the actual fields and just precede it by using ... much like the JavaScript spread syntax followed by the name.

You can go to your WP Admin, navigate over to GraphiQL IDE, and create the same custom post type with the same fields. Copy my queries and try this yourself or go ahead and make your own.

Now that this is done, we get back the same results, but our code is much cleaner and organized in a reusable way.

Using Fragments in Faust.js

Now that we know how to make and implement fragments, let’s explore how Faust.js uses them out of the box with its default examples and create some custom ones.

Default Faust.js Fragments

The first fragments we will explore are one of the defaults that come with Faust.js. Let’s look at the front page template that renders when you visit the main path. This file is located at wp-templates/front-page.js.

import { useQuery, gql } from "@apollo/client";
import * as MENUS from "../constants/menus";
import { BlogInfoFragment } from "../fragments/GeneralSettings";
import {
  Header,
  Footer,
  Main,
  Container,
  NavigationMenu,
  Hero,
  SEO,
} from "../components";

export default function Component() {
  const { data } = useQuery(Component.query, {
    variables: Component.variables(),
  });

  const { title: siteTitle, description: siteDescription } =
    data?.generalSettings;
  const primaryMenu = data?.headerMenuItems?.nodes ?? [];
  const footerMenu = data?.footerMenuItems?.nodes ?? [];

  return (
    <>
      <SEO title={siteTitle} description={siteDescription} />
      <Header
        title={siteTitle}
        description={siteDescription}
        menuItems={primaryMenu}
      />
      <Main>
        <Container>
          <Hero title={"Fran's Front Page"} />
          <div className="text-center">
            <p>This page is utilizing the "front-page" WordPress template.</p>
            <code>./wp-templates/front-page.js</code>
          </div>
        </Container>
      </Main>
      <Footer title={siteTitle} menuItems={footerMenu} />
    </>
  );
}

Component.query = gql`
  ${BlogInfoFragment}
  ${NavigationMenu.fragments.entry}
  query GetPageData(
    $headerLocation: MenuLocationEnum
    $footerLocation: MenuLocationEnum
  ) {
    generalSettings {
      ...BlogInfoFragment
    }
    headerMenuItems: menuItems(where: { location: $headerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
    footerMenuItems: menuItems(where: { location: $footerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
  }
`;

Component.variables = () => {
  return {
    headerLocation: MENUS.PRIMARY_LOCATION,
    footerLocation: MENUS.FOOTER_LOCATION,
  };
};

At the very top of this file, we import the fragment we will use named BlogInfoFragment from the fragments directory. The next thing to focus on is the bottom of the file:

Component.query = gql`
  ${BlogInfoFragment}
  ${NavigationMenu.fragments.entry}
  query GetPageData(
    $headerLocation: MenuLocationEnum
    $footerLocation: MenuLocationEnum
  ) {
    generalSettings {
      ...BlogInfoFragment
    }
    headerMenuItems: menuItems(where: { location: $headerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
    footerMenuItems: menuItems(where: { location: $footerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
  }
`;

On the template Component, we define a query property that we assign at the top of the query block is the Component.query syntax, a GraphQL query string used to fetch the template’s data in the Faust.js template hierarchy. This is a Faust.js convention that makes it easier to load data.

Next, we pass in our fragment, which contains the fields from the WP GenralSetttings object type of title and description. Notice the syntax being ${BlogInfoFragment}. This is a technique called string interpolation or template interpolation. It allows you to dynamically insert the content of the fragment variable into the query string at that specific location. This is equivalent to defining the fragment inline, which allows us to use the fragment in the actual query operation.

In this case, the ${BlogInfoFragment} is used to include the fragment definition within the query string. The Apollo Client uses the gql function to parse the query string and understand that the ...BlogInfoFragment syntax is referencing the fragment named BlogInfoFragment.

Fragments Directory

This fragment is located at fragments/GeneralSettings.js and is imported at the top of this file.

The GeneralSettings.js file looks like this:

import { gql } from '@apollo/client';


export const BlogInfoFragment = gql`
fragment BlogInfoFragment on GeneralSettings {
title
description
}
`;

In this code block, we export the variable called BlogInfoFragment and use the gql client function from Apollo to define it. Then we create the fragment in the template literal and add the fields we want back in the fragment. In GraphQL, the template literal starts with the backtick character () and ends with another backtick. They are used to define multi-string values for queries and mutations. This is used to define the GraphQL fragment named BlogInfoFragment.

This is the directory in Faust.js which contains your fragment files that can be shared and reused when you import them into your components and queries.

The fragment directory is useful when you need a centralized location for all your fragments. This can be beneficial when multiple components share the same fragments or when you want to keep your component files less cluttered.

Colocated Fragments

Colocated fragments are what Faust.js uses in the majority of its components. Colocation refers to the practice of defining fragments in the same file or module as the component that uses them, keeping the fragment definition alongside the component’s code.

This is what we consider best practice within Faust.js for these reasons:

Code Organization: By colocating fragments in the same component that uses them, the code becomes more organized and maintainable.

Local Scope: Fragments defined within a component have local scope and are not exposed globally. This prevents naming collisions and reduces the likelihood of conflicts with other fragments defined elsewhere in the application.

Explicit Relationship: Colocated fragments establish an explicit relationship between the fragment and the component that uses it. When reading or modifying the component, developers understand the specific fragment(s) used, facilitating more manageable maintenance and updates.

Things to Consider/Best Practices

You could run into conflicts if you had two fragments with the same name, but different fields, it would cause an issue. For example:

# Component A
fragment PostFields on Post {
  title
}

# Component B
fragment PostFields on Post {
  id
}

query {
  posts {
    nodes {
      ...PostFields
    }
  }
}

In this case, the query is using the PostFields fragment, but WPGraphQL does not know which version of PostFields to use since there are two with the same name. This results in an invalid query that will not execute.

This example is valid:

fragment PostTitle on Post {
  title
}

fragment PostId on Post {
  id
}

{
  posts {
    nodes {
      ...PostTitle
      ...PostId
    }
  }
}

We give a unique name to our fragments ensuring each component’s fragment definition remains distinct and can be used without conflict in WPGraphQL operations.

We can even ask for the same fields in both, like so:

fragment SomeComponentOnTheTopOfThePage on Post {
  id
  title
  author {
    node {
      id
      name
    }
  }
}

fragment SomeComponentOnTheSidebar on Post {
  id
  title
  date
  featuredImage {
    node {
      id
      sourceUrl
    }
  }
}

{
  posts {
    nodes {
      ...SomeComponentOnTheTopOfThePage
      ...SomeComponentOnTheSidebar
    }
  }
}

Both components need id and title so they both declare it. This might seem redundant but it is not. If one component no longer needs the title, it can take it out of its fragment, but the title will still be queried because the other fragment still asks for it.

Each component should query for what it specifically needs. However, components should not ask for fields they don’t actually need to satisfy another component’s needs.

Let’s shift our focus back to our wp-templates/front-page.js file:

Component.query = gql`
  ${BlogInfoFragment}
  ${NavigationMenu.fragments.entry}
  query GetPageData(
    $headerLocation: MenuLocationEnum
    $footerLocation: MenuLocationEnum
  ) {
    generalSettings {
      ...BlogInfoFragment
    }
    headerMenuItems: menuItems(where: { location: $headerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
    footerMenuItems: menuItems(where: { location: $footerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
  }
`;

Let’s look at the bottom of the file. The colocated fragment is${NavigationMenu.fragments.entry}. The ${NavigationMenu.fragments.entry} syntax includes the entry fragment from the NavigationMenu fragment collection. It allows the fields defined in the entry fragment to be used in the query.

This fragment is part of the NavigationMenu object and is defined in the components/NavigationMenu.js file:

import classNames from 'classnames/bind';
import { gql } from '@apollo/client';
import Link from 'next/link';
import flatListToHierarchical from '../../utilities/flatListToHierarchical';
import styles from './NavigationMenu.module.scss';
import stylesFromWP from './NavigationMenuClassesFromWP.module.scss';

let cx = classNames.bind(styles);
let cxFromWp = classNames.bind(stylesFromWP);

export default function NavigationMenu({ menuItems, className }) {
  if (!menuItems) {
    return null;
  }

  // Based on https://www.wpgraphql.com/docs/menus/#hierarchical-data
  const hierarchicalMenuItems = flatListToHierarchical(menuItems);

  function renderMenu(items) {
    return (
      <ul className={cx('menu')}>
        {items.map((item) => {
          const { id, path, label, children, cssClasses } = item;

          // @TODO - Remove guard clause after ghost menu items are no longer appended to array.
          if (!item.hasOwnProperty('__typename')) {
            return null;
          }

          return (
            <li key={id} className={cxFromWp(cssClasses)}>
              <Link href={path ?? ''}>{label ?? ''}</Link>
              {children.length ? renderMenu(children, true) : null}
            </li>
          );
        })}
      </ul>
    );
  }

  return (
    <nav
      className={cx(['component', className])}
      role="navigation"
      aria-label={`${menuItems[0]?.menu?.node?.name} menu`}>
      {renderMenu(hierarchicalMenuItems)}
    </nav>
  );
}

NavigationMenu.fragments = {
  entry: gql`
    fragment NavigationMenuItemFragment on MenuItem {
      id
      path
      label
      parentId
      cssClasses
      menu {
        node {
          name
        }
      }
    }
  `,
};

At the very bottom of the file are the fields we ask for in the fragment as follows:

 fragment NavigationMenuItemFragment on MenuItem {
      id
      path
      label
      parentId
      cssClasses
      menu {
        node {
          name
        }
      }
    }

The actual fragment is defined in the child component (NavigationMenu.js) that uses it explicitly within its component. It is then reused into a parent component (front-page.js)that consumes it and renders it along with other fragments in the query.

Custom Fragment Examples

Now that we have an example of default fragments in Faust.js, let’s explore some custom ones in this repo.

Using the custom post types we made for this article, let’s create a query block and fragments for them.

The file we are looking at is located at components/MovieCard.js.

import { gql, useQuery } from "@apollo/client";
import Link from "next/link";

const GET_MOVIES = gql`
  query GET_MOVIES {
    movies {
      nodes {
        ...MovieFragment
      }
    }
    actors {
      nodes {
        ...ActorFragment
      }
    }
  }

  fragment MovieFragment on Movie {
    title
    id
    slug
    uri
  }

  fragment ActorFragment on Actor {
    title
    id
    slug
    uri
  }
`;

function MovieList() {
  const { loading, error, data } = useQuery(GET_MOVIES);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <h2>Movies</h2>
      <ul>
        {data.movies.nodes.map((movie) => (
          <li key={movie.id}>
            <Link href={`${movie.uri}`}>
              <a>{movie.title}</a>
            </Link>
          </li>
        ))}
      </ul>

      <h2>Actors</h2>
      <ul>
        {data.actors.nodes.map((actor) => (
          <li key={actor.id}>
            <Link href={`${actor.uri}`}>
              <a>{actor.title}</a>
            </Link>
          </li>
        ))}
      </ul>
    </div>
  );
}

export default MovieList;

Let’s focus on the top of the file where our WPGraphQL Query and Fragment is located:

const GET_MOVIES = gql`
  query GET_MOVIES {
    movies {
      nodes {
        ...MovieFragment
      }
    }
    actors {
      nodes {
        ...ActorFragment
      }
    }
  }

  fragment MovieFragment on Movie {
    title
    id
    slug
    uri
  }

  fragment ActorFragment on Actor {
    title
    id
    slug
    uri
  }
`;



fragment ActorFragment on Actor {
title
id
slug
uri
}
`;

The MovieFragment and ActorFragment are defined inline within the GraphQL query using the fragment keyword. They are then referenced using the spread syntax (...) within the GET_MOVIES query to include the fragment fields in the response which are at the bottom of the query.

Nested Fragments

We not only included the Movie data in a fragment, but we also nested the Actor data fragment in the query block. This is useful for larger applications where you could have multiple nested fragments that go on and on.

Along with the main benefits of regular fragments, nested fragments also allow developers to have composition. This enables you to build up more complex fragments by including smaller fragments within them. You can nest fragments within other fragments, creating a hierarchy of reusable building blocks. This modular approach makes composing and customizing queries based on specific needs easier.

If you have a fragment that needs to be shared across multiple components, you can have these live in the fragments folder, as stated earlier in the article. The query would look like this instead:

const GET_MOVIES = gql`
  ${MovieFragment}
  ${ActorFragment}
  query GET_MOVIES {
    movies {
      nodes {
        ...MovieFragment
      }
    }
    actors {
      nodes {
        ...ActorFragment
      }
    }
  }

Then we would go into the fragments folder and create our fragments there. Once that is done, we would import them into the component using them.

Conclusion

I hope this article provided a better understanding of using fragments with WPGraphQL and Faust.js.

As always, super stoked to hear your feedback and any questions you might have on headless WordPress. Hit us up on our Discord channel!

Working with the Apollo Client in Faust.js

Fran Agulto — Fri, 24 Mar 2023 14:35:51 +0000

In this article, I will discuss how to work with the Apollo Client, the new GraphQL client library that is used in the Faust.js framework.

The New Faust.js

Faust.js is the front-end JavaScript framework built on top of Next.js, created to make developing headless WordPress sites easier. The idea of this new version is to make a parity between the WordPress world that a developer might be used to but replicate it as much as possible in the JavaScript front-end world.

The Apollo Client

Faust uses Apollo for its GraphQL client. The Apollo client is a data-fetching library for JavaScript that enables you to manage both local and remote data with GraphQL. It has features you can use for fetching, modifying app data, and caching. We are going to focus on how to use it in Faust.

Usage in Faust.js

Within Faust, you can use the client in your components and pages. Take this example here from the Faust docs:

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

export default function Page(props) {
  const { data } = useQuery(Page.query);
  const { title, description } = data.generalSettings;
  return(
    <h1>{title}</h1>
    <p>{description}</p>
  )
}

Page.query = gql`
  query {
    generalSettings {
      title
      description
    }
  }
`

Let’s go over what is happening in this file. At the top of the file, graphql and the useQuery hook from Apollo is being imported into the file. Then we have a default function called Page that will render the title and description of the general settings from your WPGraphQL API. After passing the props into the Page function, we create a variable that contains the data object that is the destructured response from the useQuery hook provided by Apollo. This then takes Page.query as a parameter.

At the bottom of the file is our actual GraphQL query which Page.query is coming from as a parameter. We are calling in the constant variable with the useQuery hook.

Back above the return statement, we have an object that contains the destructured fields queried which are the title and description from the data in WordPress generalSettings.

It co-locates the GraphQL query within the same file. You can also import and use queries from a file.

The benefit of Faust is that you don’t have to create the client object in your codebase. It is automatically created when you first import the @faustwp-core package. Instead, you can customize it by using a plugin filter.

Custom plugin filter 🔌: Pagination example

For this article, let’s create a custom plugin filter to use cursor-based pagination in Faust.js with Apollo. If you need a deeper understanding of pagination, please check out this article I wrote on Pagination in Headless WP.

The first thing we need to do is go into the components folder at the root of the Faust project. In the components folder, create a file called LoadMorePost.js and paste this code block in the file:

import { useQuery, gql } from "@apollo/client";
import Link from "next/link";

const GET_POSTS = gql`
  query getPosts($first: Int!, $after: String) {
    posts(first: $first, after: $after) {
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        node {
          id
          databaseId
          title
          slug
        }
      }
    }
  }
`;

const BATCH_SIZE = 5;

export default function LoadMorePost() {
  const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
    variables: { first: BATCH_SIZE, after: null },

  });

  console.log(data);

  if (error) {
    return <p>Sorry, an error happened. Reload Please</p>;
  }

  if (!data && loading) {
    return <p>Loading...</p>;
  }

  if (!data?.posts.edges.length) {
    return <p>no posts have been published</p>;
  }

  const posts = data.posts.edges.map((edge) => edge.node);
  const haveMorePosts = Boolean(data?.posts?.pageInfo?.hasNextPage);

  return (
    <>
      <ul style={{ padding: "0" }}>
        {posts.map((post) => {
          const { databaseId, title, slug } = post;
          return (
            <li
              key={databaseId}
              style={{
                border: "2px solid #ededed",
                borderRadius: "10px",
                padding: "2rem",
                listStyle: "none",
                marginBottom: "1rem",
              }}
            >
              <Link href={`${slug}`}>{title}</Link>
            </li>
          );
        })}
      </ul>
      {haveMorePosts ? (
        <form
          method="post"
          onSubmit={(event) => {
            event.preventDefault();
            fetchMore({ variables: { after: data.posts.pageInfo.endCursor } });
          }}
        >
          <button type="submit" disabled={loading}>
            {loading ? "Loading..." : "Load more"}
          </button>
        </form>
      ) : (
        <p>✅ All posts loaded.</p>
      )}
    </>
  );
}

Let’s break this file down into chunks. At the top of the file, I am importing the useQuery hook and gql provided by the Apollo client that I am using as well as next/link from Next.js. We will need these imports in this file.

The next thing you see is the query we created with cursor-based pagination.

const GET_POSTS = gql`
  query getPosts($first: Int!, $after: String) {
    posts(first: $first, after: $after) {
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        node {
          id
          databaseId
          title
          slug
        }
      }
    }
  }
`;

const BATCH_SIZE = 5;

After that, I have a default components function called LoadMorePost. In this function, I am utilizing the useQuery hook in Apollo to pass in my query called GET_POSTS from the top of the file.

Next, I have variables that I pass in, which is the batch size I defined to be 5 , and after null which tells the query to start from the beginning of the batch. This function gets fired off each time the user clicks the “load more” button.

export default function LoadMorePost() {
  const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
    variables: { first: BATCH_SIZE, after: null },

  });

  console.log(data);

  if (error) {
    return <p>Sorry, an error happened. Reload Please</p>;
  }

  if (!data && loading) {
    return <p>Loading...</p>;
  }

  if (!data?.posts.edges.length) {
    return <p>no posts have been published</p>;
  }

There are 2 variables that get set next. The first variable is posts which is taking the data that Apollo gives us back and drilling down into it with the posts and their nested data. The second variable is haveMorePosts which checks if we have more posts to load but if there are no more posts we will have to execute something else.

const posts = data.posts.edges.map((edge) => edge.node);
const haveMorePosts = Boolean(data?.posts?.pageInfo?.hasNextPage);

So now we can display our posts with a return statement with some data drilling within the levels of nesting that comes from the query.

Focusing now on the return statement, we have a <ul> tag. Within that tag, we are mapping over posts and returning a single post with a databaseId, title, and its slug. For each of those, we are displaying a list item with a <li> tag. This list item will have a title that has a link to the actual individual blog post’s page.

return (
    <>
      <ul style={{ padding: "0" }}>
        {posts.map((post) => {
          const { databaseId, title, slug } = post;
          return (
            <li
              key={databaseId}
              style={{
                border: "2px solid #ededed",
                borderRadius: "10px",
                padding: "2rem",
                listStyle: "none",
                marginBottom: "1rem",
              }}
            >
              <Link href={`${slug}`}>{title}</Link>
            </li>
          );
        })}
      </ul>

Lastly, we have to add a “load more” button. This button when clicked will load the next batch of posts from the cursor’s point. In order to do this, we take our haveMorePosts boolean and if we do have more, we will display a form with a button inside of it. When that button is clicked, we have a onSubmit handler that calls the fetchMorefunction in Apollo and passes in the variable called after that grabs the current end cursor, which is the unique ID that represents the last post in the data set to grab the next 5 after that end cursor.

  {haveMorePosts ? (
        <form
          method="post"
          onSubmit={(event) => {
            event.preventDefault();
            fetchMore({ variables: { after: data.posts.pageInfo.endCursor } });
          }}
        >
          <button type="submit" disabled={loading}>
            {loading ? "Loading..." : "Load more"}
          </button>
        </form>
      ) : (
        <p>✅ All posts loaded.</p>
      )}
    </>
  );
}

Now that we have created our component in Faust for a paginated page to load posts in batches of 5, the next step is to create a page to test this out. Navigate to the pages directory in the root of the project and create a file called pagination.js.

In that file, copy and paste this code block in:

import Head from "next/head";

import LoadMorePost from "../components/LoadMorePost";

export default function LoadMore() {
  return (
    <>
      <Head>
        <title>Load More</title>
      </Head>

      <main>
        <h1>Load More Example</h1>
        <LoadMorePost />
      </main>
    </>
  );
}

In this file, we are importing the component into this file and exporting it as a default function, returning it to render on the page.

Custom Plugin Creation in Faust for the client object

The Apollo client can implement relay-style pagination with the relay spec using merge and read functions, which means all the details of connections, edges and pageInfo can be abstracted away, into a single, reusable helper function. WPGraphQL follows the relay spec as well.

What we need to do is create a plugin for relay-style pagination in order for Faust to utilize that function from Apollo.

In order to create a Faust plugin, we are going to use its apply method which is a JavaScript class. The apply method has a parameter called hooks which is passed from @wordpress/hooks.

The first step is to go to the root of the project and create a folder called plugins. In this plugin folder, create a file called RelayStylePagination.js. Copy and paste this code block into that file:

import { relayStylePagination } from "@apollo/client/utilities";

export class RelayStylePagination {
  apply(hooks) {
    const { addFilter } = hooks;

    addFilter("apolloClientInMemoryCacheOptions", "faust", (options) => {
      return {
        ...options,
        typePolicies: {
          ...options.typePolicies,
          RootQuery: {
            ...options.typePolicies.RootQuery,
            fields: {
              posts: relayStylePagination(),
            },
          },
          ContentType: {
            fields: {
              contentNodes: relayStylePagination(),
            },
          },
        },
      };
    });
  }
}

At the top of the file, we import the relayStylePagination function from Apollo’s utility library. Following that, we create a class component which is the basic syntax used in a Faust plugin.

Next, we have an apply method with the hooks parameter which is an object that gives you a function called addFilter. The addFilter function allows us to modify the Apollo Client’s InMemoryCacheOptions.

In the next few lines of code, we are taking the addFilter hook and calling the memory cache function options. The options are coming from the Apollo Client Cache configuration. These options allow for configuring the cache’s behavior to suit our use case. In this article, we are defining the configuration for pagination. The faust namespace follows that.

Next, we spread through our options which is a callback function that can return the inMem cache options as they are. We can also merge in our own with typePolicies that we define along with other specific queries we need to merge in the future. The typePolicies is a class that defines a policy of your type in Apollo. Here, we are adding it to the RootQuery option:

  addFilter("apolloClientInMemoryCacheOptions", "faust", (options) => {
      return {
        ...options,
        typePolicies: {
          ...options.typePolicies,
          RootQuery: {
            ...options.typePolicies.RootQuery

The last few lines of code are where we are defining our fields of the posts type. Once those are defined, we can now use the relay spec used by WPGraphQL to tell Apollo and its spec in our pagination method to go ahead and append the previous and next list together using cursor-based pagination by calling the relayStylePagination function provided. Another thing to note is I also added ContentType to expose the contentNodes fields in case of using something like search functionality.

   fields: {
              posts: relayStylePagination(),
            },
          },
          ContentType: {
            fields: {
              contentNodes: relayStylePagination(),
            },
          },
        },
      };
    });
  }
}

Lastly, we need to go to our faust.config.js file to imbed it into the experimentalPlugins key as a value like so:

import { setConfig } from "@faustwp/core";
import templates from "./wp-templates";
import possibleTypes from "./possibleTypes.json";
import { RelayStylePagination } from "./plugins/RelayStylePagination";

/**
 * @type {import('@faustwp/core').FaustConfig}
 **/
export default setConfig({
  templates,
  experimentalPlugins: [new RelayStylePagination()],
  possibleTypes,
});

Generating possible types in Apollo

Before you run the dev server, make sure you type the command npm run generate since we updated the schema. The Apollo client requires that we provide a possibleTypes object that maps over our updated schema. The Faust framework provides the command script for you.

Stoked! Once you have added it to the config file in the plugins, this will allow you to have the pagination you expect when the user clicks your load more button and expects the next batch of posts!!

Previous and Next Post Link extension of WPGraphQL

The last piece I want to cover is using the WP Template to your advantage to create components and where those GraphQL queries will live and co-locate.

Out of the box, WPGraphQL does not have the ability to expose and query for previous and next post. The pagination fields plugin will allow us to modify the GraphQL schema and accomplish this.

Once this plugin is downloaded into your WP admin, you can now query WPGraphQL for the links. The query I made looks like this which you can run in GraphiQL IDE with the slug as the query variable:

 query getPost($slug: ID!) {
    post(id: $slug, idType: SLUG) {
      databaseId
      title
      content
      slug
      previousPost {
        title
        slug
      }
      nextPost {
        title
        slug
      }
    }
  }

I am querying for a single post via its slug as the variable. At the bottom of the query is where I am able to also query for the previous and next posts with the single post query as the starting point.

Finalizing Previous and Next posts in Faust.js

Back in my faust.js app, navigate to the components directory at the root of the project. From there, go to the Footer folder and create a file called PaginatedFooter.js and copy this block and paste it in:

import Link from "next/link";

export default function PaginatedFooter({ post }) {
  const { previousPost, nextPost } = post;
  return (
    <>
      <footer style={{ display: "flex", textAlign: "center" }}>
        {previousPost ? (
          <div
            style={{
              border: "2px solid #ddd",
              padding: "1rem",
            }}
          >
            <Link href={`${previousPost.slug}`}>
              <a>👈 {previousPost.title}</a>
            </Link>
          </div>
        ) : null}
        {nextPost ? (
          <div
            style={{
              border: "2px solid #ddd",
              padding: "1rem",
              marginLeft: "1rem",
            }}
          >
            <Link href={`${nextPost.slug}`}>
              <a>{nextPost.title} 👉</a>
            </Link>
          </div>
        ) : null}
      </footer>
    </>
  );
}

At the top of the file, I am importing Link from next/link using Next.js’s client-side navigation to link pages.

Then I have a default function called PaginatedFooter that is accepting the post data as its props. The following is a constant variable that destructures the post props of previousPost and nextPost which we now have exposed and are querying from WPGraphQL.

export default function PaginatedFooter({ post }) {
  const { previousPost, nextPost } = post;

Lastly, I have a return statement wrapped in a fragment that will render a footer tag. In this footer tag, I have previousPost, and if the post does exist, we display that previous post title.

Using next/link, the user has access to a clickable link to route them to that previous post page. Otherwise, if we do not have a previous post, it will render null, and nothing will appear.

After that, we have a similar JSX called nextPost which does the exact same thing as previousPost except it will show and render the next post.

return (
    <>
      <footer style={{ display: "flex", textAlign: "center" }}>
        {previousPost ? (
          <div
            style={{
              border: "2px solid #ddd",
              padding: "1rem",
            }}
          >
            <Link href={`${previousPost.slug}`}>
              <a>👈 {previousPost.title}</a>
            </Link>
          </div>
        ) : null}
        {nextPost ? (
          <div
            style={{
              border: "2px solid #ddd",
              padding: "1rem",
              marginLeft: "1rem",
            }}
          >
            <Link href={`${nextPost.slug}`}>
              <a>{nextPost.title} 👉</a>
            </Link>
          </div>
        ) : null}
      </footer>
    </>
  );
}

This component is now ready to be embedded into a single-page WP template.

Faust.js WordPress templates

Faust.js provides a JavaScript version of the WordPress template hierarchy and its system. Let’s utilize this system for our paginated footer component with the single.js file which is the WP template component that renders the single-post details page.

Navigating to the wp-templates/single.js, copy and paste over the current boilerplate code already in this file with this block:

import { gql } from "@apollo/client";
import PaginatedFooter from "../components/Footer/PaginatedFooter";
import * as MENUS from "../constants/menus";
import { BlogInfoFragment } from "../fragments/GeneralSettings";
import {
  Header,
  Main,
  Container,
  EntryHeader,
  NavigationMenu,
  ContentWrapper,
  FeaturedImage,
  SEO,
} from "../components";

export default function Component(props) {
  // Loading state for previews
  if (props.loading) {
    return <>Loading...</>;
  }

  const { title: siteTitle, description: siteDescription } =
    props?.data?.generalSettings;
  const primaryMenu = props?.data?.headerMenuItems?.nodes ?? [];
  const footerMenu = props?.data?.footerMenuItems?.nodes ?? [];
  const { title, content, featuredImage, date, author } = props.data.post;

  return (
    <>
      <SEO
        title={siteTitle}
        description={siteDescription}
        imageUrl={featuredImage?.node?.sourceUrl}
      />
      <Header title={siteTitle} description={siteDescription} />
      <Main>
        <>
          <EntryHeader
            title={title}
            image={featuredImage?.node}
            date={date}
            author={author?.node?.name}
          />

          <Container>
            <ContentWrapper content={content} />
          </Container>
        </>
      </Main>
      <PaginatedFooter post={props.data.post} />
    </>
  );
}

Component.query = gql`
  ${BlogInfoFragment}
  ${NavigationMenu.fragments.entry}
  ${FeaturedImage.fragments.entry}
  query GetPost(
    $databaseId: ID!
    $headerLocation: MenuLocationEnum
    $footerLocation: MenuLocationEnum
    $asPreview: Boolean = false
  ) {
    post(id: $databaseId, idType: DATABASE_ID, asPreview: $asPreview) {
      title
      content
      date
      author {
        node {
          name
        }
      }
      previousPost {
        title
        slug
      }
      nextPost {
        title
        slug
      }
      ...FeaturedImageFragment
    }
    generalSettings {
      ...BlogInfoFragment
    }
    headerMenuItems: menuItems(where: { location: $headerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
    footerMenuItems: menuItems(where: { location: $footerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
  }
`;

Component.variables = ({ databaseId }, ctx) => {
  return {
    databaseId,
    headerLocation: MENUS.PRIMARY_LOCATION,
    footerLocation: MENUS.FOOTER_LOCATION,
    asPreview: ctx?.asPreview,
  };
};

There are 109 lines of code in this example so let’s break this down at a high level and then I shall focus on the changes I made to the actual boilerplate starter code with my own customization.

The templates in Faust as you see in the code block have 3 main parts: Component, Query, and Variable. Please refer to the Faust docs to get a deeper explanation of what each does.

Let’s start by focusing on the query layer of the template. At the bottom of the file, I have customized the query to ask for the previousPost and nextPost fields as shown:

Component.query = gql`
  ${BlogInfoFragment}
  ${NavigationMenu.fragments.entry}
  ${FeaturedImage.fragments.entry}
  query GetPost(
    $databaseId: ID!
    $headerLocation: MenuLocationEnum
    $footerLocation: MenuLocationEnum
    $asPreview: Boolean = false
  ) {
    post(id: $databaseId, idType: DATABASE_ID, asPreview: $asPreview) {
      title
      content
      date
      author {
        node {
          name
        }
      }
      previousPost {
        title
        slug
      }
      nextPost {
        title
        slug
      }

The variables are already set to what I need, so the last thing I have to do is go back up to the top of the component which is the rendering layer and add the PaginatedFooter component after importing it at the top within the return statement. Then I can pass in and destructure the post props data in the PaginatedFooter component:

return (
    <>
      <SEO
        title={siteTitle}
        description={siteDescription}
        imageUrl={featuredImage?.node?.sourceUrl}
      />
      <Header title={siteTitle} description={siteDescription} />
      <Main>
        <>
          <EntryHeader
            title={title}
            image={featuredImage?.node}
            date={date}
            author={author?.node?.name}
          />

          <Container>
            <ContentWrapper content={content} />
          </Container>
        </>
      </Main>
      <PaginatedFooter post={props.data.post} />
    </>
  );

Super Stoked! First, run npm run generate for the types and then run this on the dev server. Let’s see this now work on the browser:

Conclusion 🚀

Faust.js and its new GraphQL client Apollo give developers a better way to develop headless WordPress.

I hope you have a better understanding of how to work with Apollo in Faust.js. As always, super stoked to hear your feedback and any questions you might have on headless WordPress. Hit us up in our discord!

Pagination in Headless WordPress with WPGraphQL, Apollo, & Next.js

Fran Agulto — Tue, 07 Feb 2023 16:26:19 +0000

In this article, I will discuss how WPGraphQL does cursor-based pagination in headless WordPress along with using Next.js and Apollo GraphQL for my client.

Pagination 📃

Pagination on the web is defined as a process of breaking or separating the content of a website into different pages. The user can use links such as “next,” “previous” and page numbers to navigate between pages and display sets of data when there is too much data to display all of the records at one time.

Cursor-based Pagination in WPGraphQL

Out of the box, WPGraphQL ships with what is called cursor-based pagination. This method loads the initial set of records and provides a cursor which is the reference point for the next request to utilize it and make the request for the next batch of records.

Traditional WordPress uses what is called offset-based pagination. This method groups post within the page numbers, essentially putting parameters within the client requests with a specific limit or number of results and then offset, the number of records that need to be skipped.

I won’t go too deep into the pros and cons of each in this article. Please check out Jason Bahl’s article here if you want to get a deeper dive into each method.

WPGraphQL Queries with Cursor-based pagination 🐘

Let’s navigate to the WP Admin and GraphiQL IDE now to discuss how to query WPGraphQL with cursor-based pagination. Below is a screenshot of my initial query with the fields and arguments that come out of the box for pagination with WPGraphQL:

In this initial query, I am asking for a list of my posts, with the arguments of grabbing the first 3 posts and then after that "null" or starting from the beginning of the list.

What if instead of starting at the beginning of the list, I want to request the list of posts after the first 3? This is where the cursor field and pageInfo type come in.

The pageInfo type has 2 fields called hasNextPage and endCursor. The hasNextPage field allows you to find out if you have more pages with your posts on that data set. The endCursor field is a unique identifier string that represents the last post of the data set you are requesting. It points to that last post on the request as shown here:

Essentially, I can now ask for every post before or after that unique identifier string that endCursor gives me instead of starting from the beginning. In this case, the post tied to that unique ID is "
Obi-Wan". When I grab the unique ID string and use it with the after argument instead of null, the query will start from that post and give me all the posts after it:

This opens up a realm of other possibilities. You can just swap out the end cursor and fire off queries to get the next subset of results after the last one from that cursor. You can do it bi-directionally as well where you can get the last 3 before the end cursor, paginating both forward and backward.

There are performance gains in this method. Because it uses the unique ID to locate the record and then counts forward or backward from that ID instead of loading every dataset in the case of offset pagination, it requires fewer resources in loading batches of data.

Let's re-write our query so that we can dynamically pass in the argument in the fields instead of hard coding the string, like so:

query getPosts($first: Int!, $after: String) {
    posts(first: $first, after: $after) {
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        node {
          id
          databaseId
          title
          slug
        }
      }
    }
  }

We are accepting input arguments first which is an integer and after which is a string. In our front-end app, we can pass in the first 3 then when the user hits the load more button, our app then grabs the end cursor and will pass in different query variables to get the next set of data results on whichever end cursor string was tied to that post.

This query is now ready to use on our first pagination example called Load More which will be used in our Next.js front-end using the Apollo client.

Load-More in Next.js and Apollo

In my Next.js application, I have a file called LoadMorePost.js which is a component that lives in my component folder:

import { useQuery, gql } from "@apollo/client";
import Link from "next/link";

const GET_POSTS = gql`
  query getPosts($first: Int!, $after: String) {
    posts(first: $first, after: $after) {
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        node {
          id
          databaseId
          title
          slug
        }
      }
    }
  }
`;

const BATCH_SIZE = 5;

export default function LoadMorePost() {
  const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
    variables: { first: BATCH_SIZE, after: null },
    notifyOnNetworkStatusChange: true,
  });

  if (error) {
    return <p>Sorry, an error happened. Reload Please</p>;
  }

  if (!data && loading) {
    return <p>Loading...</p>;
  }

  if (!data?.posts.edges.length) {
    return <p>no posts have been published</p>;
  }

  const posts = data.posts.edges.map((edge) => edge.node);
  const haveMorePosts = Boolean(data?.posts?.pageInfo?.hasNextPage);

  return (
    <>
      <ul style={{ padding: "0" }}>
        {posts.map((post) => {
          const { databaseId, title, slug } = post;
          return (
            <li
              key={databaseId}
              style={{
                border: "2px solid #ededed",
                borderRadius: "10px",
                padding: "2rem",
                listStyle: "none",
                marginBottom: "1rem",
              }}
            >
              <Link href={`/blog/${slug}`}>{title}</Link>
            </li>
          );
        })}
      </ul>
      {haveMorePosts ? (
        <form
          method="post"
          onSubmit={(event) => {
            event.preventDefault();
            fetchMore({ variables: { after: data.posts.pageInfo.endCursor } });
          }}
        >
          <button type="submit" disabled={loading}>
            {loading ? "Loading..." : "Load more"}
          </button>
        </form>
      ) : (
        <p>✅ All posts loaded.</p>
      )}
    </>
  );
}

The next thing you see is the query we created in GraphiQL back in our WordPress admin with the assistance of WPGraphQL which will allow us to fire off requests to WPGraphQL and use cursor-based pagination.

The following line shows the number of posts I want to grab in a constant in BATCH_SIZE. When the user hits the load more button, it will populate 5 posts in each load.

const GET_POSTS = gql`
  query getPosts($first: Int!, $after: String) {
    posts(first: $first, after: $after) {
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        node {
          id
          databaseId
          title
          slug
        }
      }
    }
  }
`;

const BATCH_SIZE = 5;

After that, I have a default components function called LoadMorePost. In this function, I am making use of the useQuery hook in Apollo to pass in my query called GET_POSTS from the top of the file. Next, I have variables that I pass in, which was the batch size I defined to be 5 and after null or start from the beginning. This function gets fired off each time the user clicks the “load more” button.

Following that, I have some if conditionals that invoke execution of possible states if an “error,” “loading,” or if we have no posts and the request has finished then we have no more posts published. If those checks have all passed, it means we have posts to be displayed.

export default function LoadMorePost() {
  const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
    variables: { first: BATCH_SIZE, after: null },
    notifyOnNetworkStatusChange: true,
  });

  if (error) {
    return <p>Sorry, an error happened. Reload Please</p>;
  }

  if (!data && loading) {
    return <p>Loading...</p>;
  }

  if (!data?.posts.edges.length) {
    return <p>no posts have been published</p>;
  }

There are 2 variables that get set next. The first variable is posts which is taking the data that Apollo gives us back and drilling down into it with the posts and their nested data. The second variable is haveMorePosts which checks if we have more posts to load but if there are no more posts we will have to execute something else.

 const posts = data.posts.edges.map((edge) => edge.node);
  const haveMorePosts = Boolean(data?.posts?.pageInfo?.hasNextPage);

So now we can display our posts with a return statement with some data drilling within the levels of nesting that comes from the query.

Focusing now on the return statement, we have a <ul> tag. Within that tag, we are mapping over posts and returning a single post with a databaseId, title, and its slug. For each of those, we are displaying a list item with a <li>tag. This list item will have a title that has a link to the actual individual blog post’s page.

  <ul style={{ padding: "0" }}>
        {posts.map((post) => {
          const { databaseId, title, slug } = post;
          return (
            <li
              key={databaseId}
              style={{
                border: "2px solid #ededed",
                borderRadius: "10px",
                padding: "2rem",
                listStyle: "none",
                marginBottom: "1rem",
              }}
            >
              <Link href={`/blog/${slug}`}>{title}</Link>
            </li>
          );
        })}
      </ul>

Lastly, we have to add a “load more” button. This button when clicked will load the next batch of posts from the cursor’s point. In order to do this, we take our haveMorePosts boolean and if we do have more, we will display a form with a button inside of it. When that button is clicked, we have a onSubmit handler that calls the fetchMore function in Apollo and passes in the variable called after that grabs the current end cursor, which is the unique ID that represents the last post in the data set to grab the next 5 after that end cursor.

 {haveMorePosts ? (
        <form
          method="post"
          onSubmit={(event) => {
            event.preventDefault();
            fetchMore({ variables: { after: data.posts.pageInfo.endCursor } });
          }}
        >
          <button type="submit" disabled={loading}>
            {loading ? "Loading..." : "Load more"}
          </button>
        </form>
      ) : (
        <p>✅ All posts loaded.</p>
      )}
    </>
  );
}

This is done and I have placed this component in pages/load-more.js within my Next.js app to give it a route and a page.

Let’s see how this all looks in action:

Conclusion 🚀

Pagination is an important part and very common in modern websites and apps. In this article, I hope you took away a better understanding of how to paginate in headless WordPress with the best-in-class frameworks and tools: WPGraphQL, Next.js, and the Apollo Client.

As always, stoked to hear your feedback and any questions you might have on headless WordPress! Hit us up in our discord!

SEO in Headless WordPress with Yoast, Next.js and WPGraphQL

Fran Agulto — Wed, 02 Nov 2022 22:29:22 +0000

In this article, I will give a walk-through tutorial on how to manage Search Engine Optimization (SEO) in a headless WordPress architecture.

Prerequisites

A fundamental understanding of Next.js and the Node ecosystem
Foundational SEO best practices knowledge
A WordPress install
A basic understanding of the WPGraphQL API

Yoast SEO

Before getting into the Yoast SEO plugin, let's quickly go over what SEO is and its importance. SEO is the practice of orienting your website to rank higher on a search engine results page (SERP) so that you receive more traffic. The aim is typically to rank on the first page of Google results for search terms that mean the most to your target audience.

Yoast SEO is a WordPress plugin that improves your website’s rankings on search engines by helping you optimize your site’s content and keywords. A lot of what Yoast SEO does is automated such as analyzing a page's content and providing suggestions on how to improve it. The plugin gives you a score, tells you what problems there are and how to improve your content for SEO. But there are things that still need your input such as key phrases and meta descriptions.

In this next section, let's go over installing it and extending it with WPGraphQL.

Installing Yoast SEO and WPGraphQL extensions

To start, we need to set up and configure Yoast and WPGraphQL including its Yoast extension to expose the SEO fields in the GraphQL schema with Yoast.

Next, search for WPGraphQL and Yoast for WPGraphQL, install and activate both:

Stoked! These are all the plugins we need on the WordPress install to manage SEO in a headless setup! Let's make sure everything is working as it should be.

Head over to Posts and click on an individual post to edit it. When you are in the edit interface of the individual post, you should see an option to select Yoast SEO at the bottom of the page:

Click on that Yoast SEO option and it will reveal tools such as adding a meta description, canonical URL, breadcrumbs title, etc. There are lots of features to increase and boost your SEO. For this quick tutorial, we will focus on exposing the meta and full head of the HTML in the post in order for web crawlers to better find and index the page.

WPGraphQL and the SEO field

The WPGraphQL for Yoast extension makes it really easy and seamless to expose and query for the SEO data in the WordPress WPGraphQL schema. A SEO field is exposed in the GraphiQL IDE and you can ask specifically for what SEO data you want back.

On the side menu in your WP admin, go to the GraphiQL option on the left or the icon at the top of the navbar. In this case, I am querying for a single post by its slug as the variable and asking for the meta description, title, and the full head of the HTML page in the SEO field.

This is what my query looks like in a code block:

query PostBySlug($slug: String!) {
        generalSettings {
          title
        }
        postBy(slug: $slug) {
          id
          content
          title
          slug
          seo {
            metaDesc
            title
            fullHead
          }
        }
      }

This is what the query looks like in the GraphiQL IDE in WP Admin after you press play to run it:

You can see that it exposes the SEO data via GraphQL schema!! We get back some SEO data goodness! The next step is to get this data and consume it on our frontend UI with Next.js.

Next.js Head and Metadata

We have our WordPress install transformed into a WPGraphQL server with the SEO extension to expose that metadata. The next step is to use Next.js as our frontend app to consume that data and turn it into HTML and improve the way the search engine indexes our site.

In this tutorial, I am going to use my Next.js demo starter. Once you clone down the starter, navigate to the root of the project into the pages/[slug].js file. Go down to the getStaticProps function that contains our GraphQL query. Copy and paste this block over the existing code. It should look like this:

export async function getStaticProps({ params }) {
  const GET_POST = gql`
    query PostBySlug($id: ID!) {
      post(id: $id, idType: SLUG) {
        title
        content
        date
        seo {
          metaDesc
          fullHead
          title
        }
        author {
          node {
            firstName
            lastName
          }
        }
      }
    }
  `;

This file and query are grabbing an individual post with its related data. The SEO meta description, full head, and title are also being requested! Stoked!!

Now that our SEO data is being requested and coming through, let's show it on our site by adding it to our variable in Next.js and destructure it so we can add it to our JSX.

At the top of the [slug].js file, copy this code block and paste it over the existing code. It should look like this:

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

import Head from "next/head";

export default function SlugPage({ post }) {
  const { seo } = post;

  return (
    <div>
      <Head>
        <title>{seo.title}</title>
        <meta name="description" content={seo.metaDesc} />
        <link rel="icon" href="/favicon.ico" />
      </Head>

When we run this locally in terminal to pull up the site on the browser with npm run dev and open up the dev tools to inspect the elements in the Head tag, you should see all the SEO data that you requested:

We are now optimized for SEO using next/head which is a built-in component in Next.js that allows us to append elements at the head of each page.

Full Head and HTML Parser

Managing the entire Head of your page is made easier with the full head field within the WPGraphQL schema. The issue here is the next/head component does not support React dangerouslySetInnerHTML convention.

In order to alleviate this issue we can use the html-react-parser package. Go to terminal and install it like so in your project directory:

Once installed, go back to the [slug].js file and copy this code block from top to bottom and your full file should look like this:

import { client } from "../lib/apollo";
import { gql } from "@apollo/client";
import parse from "html-react-parser";
import Head from "next/head";

export default function SlugPage({ post }) {
  const fullHead = parse(post.seo.fullHead);
  return (
    <div>
      <Head>{fullHead}</Head>

      <main>
        <div className="siteHeader">
          <h1 className="title">{post.title}</h1>
          <p>
            ✍️ &nbsp;&nbsp;
            {`${post.author.node.firstName} ${post.author.node.lastName}`} | 🗓️
            &nbsp;&nbsp;{new Date(post.date).toLocaleDateString()}
          </p>
        </div>
        <article dangerouslySetInnerHTML={{ __html: post.content }}></article>
      </main>
    </div>
  );
}

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

  return {
    props: {
      post,
    },
  };
}

export async function getStaticPaths() {
  const paths = [];
  return {
    paths,
    fallback: "blocking",
  };
}

At the top of the file, we import the parse from html-react-parser. Then, we set a const up to call the full head and transform it into react. Once that is done, we simply add the jsx within the head tag grabbing the full head data in one object.

Going back to terminal and running it locally, we can see that it is working!!! The entire full head is showing with all the metadata and canonical URLs!

Deploy On Atlas

This works locally on our machine. Let's get it deployed and live on the internet and check to see if we get the same results.

I will use Atlas, WP Engine's Headless WordPress hosting platform, specifically built to optimize for headless. I already have an account all set up with my GitHub repo accessible on Atlas. All I need to do is push this change and trigger that build and deployment.

Once my app is deployed on Atlas, the unique URL is updated. Hit this URL, go to any of the post links on the home page and open the dev tools on its detail page. Once there, inspect the Head elements. You will see what we saw locally but now it is live on the internet!

Conclusion

SEO is an important part of your site's discoverability when it comes to Google and other search engines indexing your site and ranking them high. It makes your website more visible, and that means more traffic.

With the tools like WPGraphQL, Yoast SEO, Next.js and Atlas to host, this is made much more easier and seamless for the developer.

This tutorial covered just the basics of what Yoast SEO can do with WPGraphQL. There are a lot more features and options you can do and I would love to hear about them in our Discord channel!

If you have not used the Atlas platform and are interested, please check this link out to get a free sandbox dev account!

Planning for Headless WordPress and Atlas

Fran Agulto — Wed, 19 Oct 2022 16:59:20 +0000

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

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

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

Building a website in Headless WordPress

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

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

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

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

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

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

Workflow Steps in using Atlas

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

Atlas Abstract: What it provides

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

Continuous Integration/Continous Deployment

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

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

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

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

Atlas CDN

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

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

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

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

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

In summary, the Atlas CDN provides:

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

WordPress APIs and 3rd Party APIs

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

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

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

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

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

FAQs/Best Practices 🌐 🤓

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

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

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

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

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

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

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

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

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

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

Two main solutions that are most commonly used are:

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

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

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

Let us know your thoughts!

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

Atlas Platform Features: Deployment Previews & Webhooks

Fran Agulto — Wed, 21 Sep 2022 15:33:19 +0000

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

The Modern Developer Workflow

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

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

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

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

Deployment Previews

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

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

How Deployment Previews Work

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

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

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

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

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

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

Deployment Previews FAQs

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

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

Do Deployment Previews Count Towards My Resources?

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

What Happens if I Make Additional Commits to a PR?

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

How Do I Delete a Deployment Preview?

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

Atlas Environment Rebuild Webhooks

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

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

What is a Webhook?

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

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

Configuring Builds with Atlas Webhooks

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

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

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

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

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

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

Embed the Webhook in WordPress

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

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

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

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

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

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

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

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

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

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

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

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-07-at-4.42.17-PM-1024x575.png
This image has an empty alt attribute; its file name is Screen-Shot-2022-09-07-at-4.45.12-PM-1024x452.png
You can link back and forth between UI's conveniently as well.

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

Deployment Previews FAQs
I Don't See Deployment Previews Anywhere in the Atlas Platform
The deployment previews feature needs to be enabled on a per-environment basis, which means if you want to preview PRs submitted against your main or production branch, the setting needs to be enabled for that Atlas environment.

Do Deployment Previews Count Towards My Resources?
No, any deployment previews that you create do not count towards your plan entitlements.

What Happens if I Make Additional Commits to a PR?
If you continue to make commits to a feature branch with an open PR, Atlas will detect those changes and rebuild your deployment preview.

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

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

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

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

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

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

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-17-at-12.17.07-PM-1024x448.png
Step 2: Once you choose an app environment and click on it, you will be taken to an environment settings page. Click on the Settings link:

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-20-at-10.21.01-AM-1024x580.png
Step 3: Clicking on the Settings link takes you to the Settings page. In the lower half of the page, you will see an Environment webhook pane. Click the Create a webhook button:

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-17-at-12.25.30-PM-1024x519.png
Once you click that, an endpoint will be generated like this:

This image has an empty alt attribute; its file name is Screen-Shot-2022-09-17-at-12.29.54-PM-1024x519.png
Copy that endpoint URL because we are going to need it for our WordPress backend.

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

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

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

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

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

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

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

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

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

Please reference the docs as well for webhooks.

Stay Tuned, more Atlas features to come...

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

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

Sitemaps in Headless WordPress with Next.js

Fran Agulto — Mon, 12 Sep 2022 17:14:31 +0000

In this tutorial, you will learn how to create sitemaps in Headless WordPress using Next.js and the WP Sitemap Rest API plugin. (Just a note, if you need a foundational understanding of Next.js, please follow this tutorial by my main man Jeff Everhart.

Previously, I wrote about what Sitemaps are and the benefits of them in this article you can reference here. In the context of this blog post, we will jump right into creating the sitemaps. By the end of this tutorial you will be able to:

Create a Sitemap in Next.js that dynamically pulls your URLs from WordPress
Add your Next.js pages and paths on your Sitemap including dynamic routes

Setup your WordPress Site

The first thing we are going to do is configure your WordPress site so that we have access to the particular endpoints for our Sitemaps. We are going to use the WP Sitemap Rest API plugin. Download the plugin from the repo via zip file. Next, In WP Admin, go to the Plugins > Add Plugins option at the top right and upload the plugin.

Once you install that plugin, you expose these 4 endpoints to your REST API in WordPress:

/wp-json/sitemap/v1/totalpages
/wp-json/sitemap/v1/author?pageNo=1&perPage=1000
/wp-json/sitemap/v1/taxonomy?pageNo=1&perPage=1000&taxonomyType=category or tag
/wp-json/sitemap/v1/posts?pageNo=1&perPage=1000&postType=post or page

Easily, with this plugin, if you visit “your.wordpresssite.com”plus appending any of the 4 endpoints, you will get an object back of what those paths reflect. An example of my demo site with the first endpoint added:

Easy Peasy, now on to the Next.js frontend.

Install Dependencies

Before we go into the code, we need to install a dependency we will use in this tutorial within our Next.js project called axios. Axios will give us some helper functionality to make XMLHttpRequests from our Next.js front-end. To do this, run npm i axios in your terminal.

Environment Variables

There are a couple of endpoints we will have to set up as environment variables in our project before we create the functions needed.

In the root of your project, create a .env.local file. In this file, add your endpoints and how many items per sitemap you would want. Note that on the frontend URL, because I am using a development environment on my local machine, I am using the Next.js default of localhost with port 3000.

NEXT_PUBLIC_WORDPRESS_API_URL=https://yourwordpresssite.com
NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
NEXT_PUBLIC_ITEM_PER_SITEMAP=50

Now that we have added our environment variables in the properly named file, let’s allow our project access to them via the process.envobject.

In the root of your project, create a utils folder. In the utils folder, create a file called variables.js. In this file, add this code block:

export const wordpressUrl = process.env.NEXT_PUBLIC_WORDPRESS_URL;
export let frontendUrl = process.env.NEXT_PUBLIC_FRONTEND_URL;
export let sitemapPerPage = process.env.NEXT_PUBLIC_ITEM_PER_SITEMAP || 50; //1000

The variables we are naming above are needed so that Next.js can access those endpoints from our.env.local with the process.env object.

Next.js sitemap functions

We are going to need a few functions in order to dynamically grab the total amount of WordPress URLs to make them available to your sitemap index page and show them on the browser as well as showing our Next.js front-end URL’s.

The first step is to create a folder called lib in the root of the project. In the new lib folder, create a file called getTotalCounts.js and add this code block:

import axios from "axios";
import { wordpressUrl } from "../utils/variables";

export default async function getTotalCounts() {
  const res = await axios.get(`${wordpressUrl}/wp-json/sitemap/v1/totalpages`);
  let data = await res.data;
  if (!data) return [];
  const propertyNames = Object.keys(data);
  let excludeItems = ["user"];
  //if you want to remove any item from sitemap, add it to excludeItems array
  let totalArray = propertyNames
    .filter((name) => !excludeItems.includes(name))
    .map((name) => {
      return { name, total: data[name] };
    });

  return totalArray;
}

This file is a fetch function that is grabbing the total pages from your WordPress site and returning that data in an array. If you want to exclude any data from your sitemap you can add it to the excludeItems array as commented.

The next thing we need to create is a way to get the sitemap pages and return them for the specific type.

Back in our utils folder, create a file called getSitemapPages.js and add this code block:

import { frontendUrl, sitemapPerPage } from "./variables";

export default function getSitemapPages(item) {
  const items = [];
  for (let i = 1; i <= Math.ceil(item.total / sitemapPerPage); i++) {
    let url = `${frontendUrl}/sitemap/${item.name}_sitemap${i}.xml`;
    items.push(
      ` 
        <sitemap>
           <loc>
              ${url}
          </loc>
      </sitemap>
      `
    );
  }
  return items.join("");
}

This file is importing the variables we declared in our variables.js file. Then, it exports a function by default that is passing in the item from the total counts function we created. Once these are passed in, the front-end URL is appended with the item name and the XML path. Then we join these with the XML tags with the slug from WordPress.

We now have the necessary functions in place to generate our sitemap pages and the total number of them. The next step is to create a sitemap index page.

Sitemap Index Page

We are going to take advantage of Next.js and its page-based file routing. This means that any file I add to the pages directory in my project will correspond automatically to a route that is available.

Create a file in the pages directory of your project called sitemap.xml.js and add this code block:

import getSitemapPages from "../utils/getSitemapPages";
import getTotalCounts from "../lib/getTotalCounts";
export default function SitemapIndexPage() {
  return null;
}
export async function getServerSideProps({ res }) {
  const details = await getTotalCounts();

  let sitemapIndex = `<?xml version='1.0' encoding='UTF-8'?>
  <sitemapindex xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/siteindex.xsd"
           xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     ${details.map((item) => getSitemapPages(item)).join("")}
  </sitemapindex>`;
  res.setHeader("Content-Type", "text/xml; charset=utf-8");
  res.setHeader(
    "Cache-Control",
    "public, s-maxage=600, stale-while-revalidate=600"
  );
  res.write(sitemapIndex);
  res.end();
  return { props: {} };
}

The first thing to notice at the top of the file is the importing of the two functions we just created to generate the WordPress page types and the total counts. Then we have this page as a default function that will utilize server-side rendering since we want this page to be dynamic on every request so the sitemap is up to date.

Next, I copied a sitemap example and formatted it so that the XML tags and links show up on the browser with the response header set and the page write response set to load and end with the props returned.

Let’s get stoked now and see what this looks like on the browser. Go to your terminal and run npm run dev. You should see this:

Awesome!! We now have a dynamic sitemap in a headless WordPress setup. The next step is to add the ability to grab the URL of the sitemap path and have that route to its detail page.

Dynamic Sitemap Page Routes

We need a couple of things to make the dynamic page routes work for our sitemap. First, we need a way to generate the sitemap paths to their detail page.

Go back to the utils folder we created earlier. In this folder, create a generateSitemapPaths.js file and add this code block:

import { frontendUrl } from "./variables";

export default function generateSitemapPaths(array) {
  const items = array.map(
    (item) =>
      `
            <url>
                <loc>${frontendUrl + item?.url}</loc>
                ${
                  item?.post_modified_date
                    ? `<lastmod>${
                        new Date(item?.post_modified_date)
                          .toISOString()
                          .split("T")[0]
                      }</lastmod>`
                    : ""
                }
            </url>
            `
  );
  return items.join("");
}

This file imports our front-end URL variable and then exports a default function that passes in an array. The items variable is mapped which then returns a single item. Then we have XML tags that dynamically grab the appropriate item and concatenate that to your frontend URL, as well as the date the page was last modified. Now that we have the function needed, let’s create the dynamic route page.

Next.js makes it easy to create a dynamic file if you have a parameter like a slug that changes upon request. The naming convention for this is the bracket syntax. Create a folder in the pages directory called sitemap. In this folder, create a file called [slug].js:

In the [slug].js file, add this code block:

import getSitemapPageUrls from "../../lib/getSitemapPageUrls";
import getTotalCounts from "../../lib/getTotalCounts";
import generateSitemapPaths from "../../utils/generateSitemapPaths";
export default function SitemapTagPage() {
  return null;
}
export async function getServerSideProps({ res, params: { slug } }) {
  let isXml = slug.endsWith(".xml");
  if (!isXml) {
    return {
      notFound: true,
    };
  }
  let slugArray = slug.replace(".xml", "").split("_");
  let type = slugArray[0];
  let pageNo = slugArray[1]?.match(/(\d+)/)[0] ?? null;
  let page = pageNo ? parseInt(pageNo) : null;
  let possibleTypes = await getTotalCounts();
  if (!possibleTypes.some((e) => e.name === type)) {
    return {
      notFound: true,
    };
  }
  let pageUrls = await getSitemapPageUrls({ type, page });
  if (!pageUrls?.length) {
    return {
      notFound: true,
    };
  }
  let sitemap = `<?xml version="1.0" encoding="UTF-8"?>
  <urlset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd"
  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    ${generateSitemapPaths(pageUrls)}
  </urlset>`;
  res.setHeader("Content-Type", "text/xml; charset=utf-8");
  res.setHeader(
    "Cache-Control",
    "public, s-maxage=600, stale-while-revalidate=600"
  );
  res.write(sitemap);
  res.end();
  return { props: {} };
}

There is quite a bit of code in this file. Essentially, what is happening in this file is that we are importing all of our functions at the top that we need access to for the sitemap dynamic paths.

Next, a default function is exported, calling it SitemapTagPage. We return null, then have an async function to getServerSideProps as we want this function to be server-side rendered as well on every request. Then in the response object, we pass in the params which is the slug in this case.

Our variable isXML is equal to the slug and the appended XML path ending. If this a not an xml slug and path we return it to not be found.

In the middle of the file, we declare numerous variables that we name as we need to set the array of slugs, the type, the page number using regex which extracts the number from the string, and the possible types and the total counts of those types.

Lastly, we validate this to see if it properly is aligned with our sitemap index page, otherwise, we throw a 404. Once that is done, we have our XML tags formatted and the appropriate responses.

Let’s try this now and see if this works in the browser. Go back to the terminal and run npm run dev. Once the sitemap index page shows on the browser, grab any URL on the
sitemap and put it in the search bar:

I chose to grab my post page URL at sitemap/post_sitemap1.xml. I followed that link in the search bar and got the post sitemap details! Stoked!! 🎉

Next.js Pages

Finally, we need to account for our Next.js pages on our front-end. In order to do this, let’s go to our pages directory and add a file called sitemapnextjs.xml.js. In this file, add this code block:

import React from "react";
import * as fs from "fs";
const Sitemap = () => {
  return null;
};

export const getServerSideProps = async ({ res }) => {
  const BASE_URL = "http://localhost:3000";

  const staticPaths = fs
    .readdirSync("pages")
    .filter((staticPage) => {
      return ![
        "api",
        "about",
        "_app.js",
        "_document.js",
        "404.js",
        "sitemap.xml.js",
      ].includes(staticPage);
    })
    .map((staticPagePath) => {
      return `${BASE_URL}/${staticPagePath}`;
    });

  const dynamicPaths = [`${BASE_URL}/name/1`, `${BASE_URL}/name/2`];

  const allPaths = [...staticPaths, ...dynamicPaths];

  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
      ${allPaths
        .map((url) => {
          return `
            <url>
              <loc>${url}</loc>
              <lastmod>${new Date().toISOString()}</lastmod>
              <changefreq>monthly</changefreq>
              <priority>1.0</priority>
            </url>
          `;
        })
        .join("")}
    </urlset>
  `;

  res.setHeader("Content-Type", "text/xml");
  res.write(sitemap);
  res.end();

  return {
    props: {},
  };
};

export default Sitemap;

At the top of the file, we are importing React, and fs to access local storage. Next, we return null as we want this to not render or return anything in the component. Instead, we will use the getServerSideProps function, export it as a const, then pass in the response object, just like we did in the sitemap index page to server-side render for fresh, up-to-date sitemap data.

Then we declare our base URL variable, in this case, I am using the dev server off localhost:3000.

Once we set the fs to our static paths, we enable a way within the object to filter through our static pages in Next.js within an array and input which ones we do not want on the sitemap. I just added the default pages Next.js comes with as an example.

The next step is to account for the dynamic paths that you have in Next.js, apart from WordPress. We set a const for our dynamic paths and make it equal to an array where we get our base URL and our hard coded path. (I just named it “name” but you can name it in relation to whatever your dynamic route file is)

The last things we need to do are to set the const for all our paths and iterate through them with the spread operator and expand all of them in an array.

Finally, we generate the sitemap in XML format with the appropriate response headers returning our props. Jamstoked!! We now have all the paths and the URLS in our Next.js front-end!!! 💥

Combining Next.js pages and WordPress pages in your sitemap index page

All that is left is adding our Next.js pages to our sitemap index with our WordPress pages. Go back to the sitemap.xml.js file and add this code block:

import getSitemapPages from "../utils/getSitemapPages";
import getTotalCounts from "../lib/getTotalCounts";
export default function SitemapIndexPage() {
  return null;
}
export async function getServerSideProps({ res }) {
  const details = await getTotalCounts();

  let sitemapIndex = `<?xml version='1.0' encoding='UTF-8'?>
  <sitemapindex xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/siteindex.xsd"
           xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     ${details.map((item) => getSitemapPages(item)).join("")}
     <sitemap>
     <loc>
        http://localhost:3000/sitemapnextjs.xml
    </loc>
</sitemap>
  </sitemapindex>`;
  res.setHeader("Content-Type", "text/xml; charset=utf-8");
  res.setHeader(
    "Cache-Control",
    "public, s-maxage=600, stale-while-revalidate=600"
  );
  res.write(sitemapIndex);
  res.end();
  return { props: {} };
}

The one difference in this file is the URL we added http://localhost:3000/sitemapnextjs.xml in our XML element <loc></loc>. This will allow us to show the Next.js pages on our sitemap index.

Let’s see this in action in the browser. Go back to terminal and run npm run dev. You should see this in the browser:

We now have our sitemap for Next.js pages on our index. Let’s see what all the details of our pages are in Next.js when we follow that URL:

Done!! Jamstoked! 🎉

We are finished with this walk-through tutorial! Jamstoke! With this tutorial, we hope you take away the ability to understand the importance of sitemaps and the value of utilizing them to inform search engines of your site’s page and path layout.

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

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

I want to give a major shoutout and credit to Dipankar Maikap who created the WP Sitemap Rest Api plugin and assisted me in the creation of this tutorial.

Sitemaps in Headless WordPress with Faust.js

Fran Agulto — Fri, 02 Sep 2022 14:13:52 +0000

In this article, I will discuss Sitemaps in Headless WordPress using the open source framework for Headless WordPress – Faust.js.

XML Sitemaps

An XML sitemap is a list of URLs that you want to be publicly available. It helps search engines crawl your website by giving them an exact map of all your content. There is also metadata you can pull into your sitemap which are listed in the sitemaps protocol such as when a page was last modified, video information and images.

Below is an image of a traditional WordPress XML sitemap url. The default is your WordPress URL with the added path /wp-sitemap.xml and this is baked into WordPress core from version 5 and above:

XML Sitemap Benefits

Faster Indexing: XML sitemaps will communicate with search engines. You can submit your sitemap into the Google Search Console and that helps get pages on your site indexed much faster with search engines. This increases your rank in search engine page results.
Automatic Update Notification: Google will receive automatic notifications when you publish new content or modify existing content.
Categorization of Your Content: Allows Google to know which pages go under which category so there is no guesswork.

XML Sitemaps in the Faust.js framework

Sitemaps can be complicated to create and process when you are using WordPress in a headless architecture. Thankfully, the Faust.js team at WP Engine created a feature within the framework that makes it work within a single file within the pages directory.

Setup

The first step is to install the Faust.js framework with the following command in your terminal:

npx create-next-app \
    -e https://github.com/wpengine/faustjs/tree/main \
    --example-path examples/next/getting-started \
    --use-npm \
    my-app
cd my-app

Copy the sample environment template:

cp .env.local.sample .env.local

Connect your WordPress site:

Navigate to your .env.local file in the root of your project and paste your WP URL as the value:

# Your WordPress site URL
NEXT_PUBLIC_WORDPRESS_URL=https://headlessfw.wpengine.com

Setting Permalinks and Reading Visibility:

Set permalinks In WP Admin >> Settings >> Permalinks to: /posts/%postname%/

Set reading settings in WP Admin >> Settings >> Reading >> Search Engine Visibility uncheck box:

Faust.js

Next, navigate back to your Faust.js app, and in the srcfolder at the projects root, go to the /pages directory. Within the pages directory, create a file and name it
sitemap.xml.tsx.

In the sitemap.xml.tsx you just created, copy and paste this code block:

import { getSitemapProps } from '@faustjs/next/server';
import { GetServerSidePropsContext } from 'next';

export default function Sitemap() {}

export function getServerSideProps(ctx: GetServerSidePropsContext) {
  return getSitemapProps(ctx, {
    sitemapIndexPath: '/wp-sitemap.xml',
    wpUrl: 'https://buddydemo1.wpengine.com',
    frontendUrl: 'http://localhost:3000',
  });
}

In this file, the first thing that is happening is the importing of the sitemap properties on the Faust.js server framework as well as importing the Server Side properties context from Next.js.

Next, we export a default function that is the Sitemap with an empty object. Once that is done, below is a function in Next.js that allows for server side rendering. Within this function, we pass in the server side props context and then return a config object with the sitemap props.

The config object requires your sitemapIndexPath property with a value of your WordPress sitemap.xml path, a wpURL property with a value of your WordPress URL, and your Faust.js frontend URL. In this case I am developing locally of localhost:3000.

Now that I have this file setup in my pages directory within Faust, I can run npm run dev to start the dev server and I am able to access my WordPress content dynamically to my Headless site. Stoked!! 🎉

Defining Next.js Pages for Sitemaps

The last thing we need to account for in our sitemap is the Next.js pages. Since we are using Headless WordPress, the front-end URLs need to be on the sitemap as well. Within the same sitemap.xml.tsx file, simply add a pages property array and place the relative paths of Next.js in the objects within the array like so:

import { getSitemapProps } from '@faustjs/next/server';
import { GetServerSidePropsContext } from 'next';

export default function Sitemap() {}

export function getServerSideProps(ctx: GetServerSidePropsContext) {
  return getSitemapProps(ctx, {
    sitemapIndexPath: '/wp-sitemap.xml',
    wpUrl: 'https://buddydemo1.wpengine.com',
    frontendUrl: 'http://localhost:3000',
    pages: [
      {
        path: '/about',
        changefreq: 'monthly',
      },
      {
        path: '/',
      },
    ],
  });
}

Running my development server again and visiting the sitemap URL, I now have my WordPress content and my Next.js content in faust-pages:

Super Jamstoked!! ⚡ of the many benefits of using a framework like Faust.js is the developer toil it removes from your plate especially in Headless WordPress. Features like sitemaps should just work simply out of the box with the ability to account for your URLs from WordPress and your front-end without too much heavy lifting.

Done! What Next?

If Faust.js is not your thing, stay tuned, I shall create another blog-post in relation to this but I will create a XML sitemap using only Next.js and Headless WordPress!!

Efficient SSG in Next.js with WPGraphQL

Fran Agulto — Thu, 04 Aug 2022 15:41:00 +0000

In this article, I will discuss best practices around Static Site Generation in Next.js with dynamic routes and static paths.

Static Site Generation

Before I dive into optimization details, let's go over quickly for context what Static Site Generation (or SSG for short) does and how it works with getStaticPaths in dynamic routes.

Next.js allows you to statically generate your site, pages and fetch data at build time with the function getStaticProps. The main reason developers choose this method is speed and performance as the static files and data are cached and served on a CDN and available right at request.

Static Paths and Dynamic Routes

When you have a site that is statically generated but you have a selection of posts on a home page and want users to be able to click that post which will route them to the details page of that individual post, you will need a route parameter for the route for that individual details page of the post. Now, Next.js does not know how many individual details pages we have and the routes associated with those pages since it depends on external data, in this case WordPress is our external data source.

We can explicitly tell Next.js what pages and routes we need to create at build time based on our WordPress data. To do this, we use the function called getStaticPaths. This runs at build time and inside it we return all the possible values of our route parameters. Then once we do, Next.js will know to generate a route and a page for each of those parameters.

How they work together

The Next.js syntax [param] allows for a page file to have the dynamic route capability based on parameters. Within this file, you can have the two functions I discussed. The getStaticPaths function which will build the paths and pages for each individual details page. The getStaticProps function fetches the data related to those individual details pages and adds the data unique to those pages statically. At a high level, this is how these two functions work together in a dynamic route page.

Next.js & WPGraphQL

When you use Next.js and WPGraphQL for Headless WordPress, an issue that you will run into is pre-rendering all your paths and pages in the function called getStaticPaths.

Building ALL pages every time a build is run leads to the WordPress server being hammered and sometimes becoming unresponsive. Another thing to consider when you do this is the long build times you will have if your site has a lot of pages.

Here are some symptoms of an unresponsive WP server examples in WPGraphQL:
SyntaxError: Unexpected token < in JSON at position 0

This code block below is a headless WordPress starter that my teammate Jeff made using Next.js. This is my getStaticPaths function at the bottom of my dynamic route file page [slug].js :

export async function getStaticPaths() {
  const GET_POSTS = gql`
    query AllPostsQuery {
      posts(first: 10000) {
        nodes {
          id
          title
          slug
          uri
        }
      }
    }
  `;
  const response = await client.query({
    query: GET_POSTS,
  });

  const posts = response?.data?.posts?.nodes;
  const paths = posts.map(({ slug }) => {
    return {
      params: {
        slug: slug,
      },
    };
  });

  return {
    paths,
    fallback: false,
  };
}

This is a similar pattern we've seen in a few popular WordPress starters such as Colby Fayock's and WebDevStudios. While this pattern feels intuitive, it can actually be problematic.

The first thing to notice at the top of this function is my GraphQL query and what it is fetching. It is fetching 10000 nodes from WPGraphQL. By default, WPGraphQL prevents more than 100 per request. If I continue to use this query, it either will only return 100 items or I will need to make bespoke modifiers in WPGraphQL to support this use case and Jason Bahl who created and maintains WPGraphQL highly advises against this.

I have a variable of paths and I am mapping through posts to grab the slug that I set it to. In the return object of the variable I have params giving us the slug of the post. Below that variable, I have a return object with the paths property getting all the paths and if that path does not exist in my prebuilt static paths is a 404 page which is fallback: false in Next.js.

When the 10000 nodes are returned, they are passed as paths and Next.js will build every single page and each page has a GraphQL query or more and is sent to the WordPress server, which then overwhelms the server. This is not optimal as I as I stated since this will not only overwhelm your server and make for a bad user experience on your site, but you will also accrue costs if your site gets larger for tools that charge for build times since your build times will continue to increase.

This is what it looks like when I run npm run build to create an optimized production build and build directory of my site within terminal:

Notice the /posts/[postSlug].js folder and file. Due to the way I have my getStaticPaths function set up, you can see that it is pre-building every single path and the time it takes to build them. Now, imagine if this was a site with hundreds or thousands of pages like ESPN. This would not be optimal. It could take hours to build every page.

An alternative to consider to fix this issue in your Dynamic Route file within your getStaticProps function in the return statement would be something like this:


export async function getStaticPaths() {
  const paths = [];
  return {
    paths,
    fallback: "blocking",
  };
}

This is the same return statement shown previously. The difference is with setting the paths as an empty array and adding fallback: "blocking" ; this tells Next.js to not pre-build pages at build time. This will instead be Server Rendered upon each visit and Statically Generated upon subsequent visits. Doing this alleviates the issue of unnecessary GraphQL queries sent to the WordPress server and really long build times.

nodeByUri Query

One thing to note is the change of your query when you are going to server render your pages. The initial issue was that the query was asking for 10,000 posts and sent the post through the context of each path being pre-built. What we need now is a way to get the url out of the context and then query the page based on that using nodeByUri.

Here is a logic example:

 export const SEED_QUERY = gql`
query GetNodeByUri($uri: String!) {
    node: nodeByUri(uri: $uri) {
      ...NodeByUri
    }
  }


 if ( context.resolvedUrl ) {
    params = context?.params ?? null;
    resolvedUrl = context?.resolvedUrl ?? null;
    
  } else if ( context?.params?.WordPressNode ) {
    params = context?.params ?? null;
    isStatic = true;
    resolvedUrl = context?.params?.WordPressNode ? context?.params?.WordPressNode.join('/') : null;
  }

This code example is getting the url of the page the user is visiting, then using that in the nodeByUri query. This allows users to do fallback: blocking, paths: [] but still have the context needed to grab the data and build the page. This video gives a walk through as well for reference if you need an overview of the query.

This is what my production build looks like now with this syntax change when I run npm run build :

In this image, the /posts/[slug].js folder and file is not pre-building the paths. It is allowing paths and pages to be generated on the fly by Server Rendering. No unnecessary path and page prebuilds.

If you have really important pages, you could put them in paths like this:

export async function getStaticPaths() {
    return {
        paths: [
          '/some-really-important-page',
        ],
        fallback: 'blocking'
    }
}

This tells Next.js to build only the paths specified in the array. The rest are Server Rendered.

ISR Option

If you have content editors who want pages to be available close to the time that the content is published in WordPress and not after each new build step is complete, Incremental Static Regeneration or ISR for short is the best option. Even for cases that have very important pages you want to make sure are always static.

The code within your getStaticProps function in your Dynamic Route file to invoke ISR would look something like this:

export async function getStaticProps() {
   return {
    props: {
      posts,
    },
    // Next.js will attempt to re-generate the page:
    // - When a request comes in
    // - At most once every 10 seconds
    revalidate: 10, // In seconds
  }
}

This is saying that every 10 seconds, Next.js will will revalidate the data on and this page upon user request. The caveat here is that the initial user who request this page will get the stale data but every user and request for this page after that initial request will get the fresh data within the timed interval you set. (You can set whatever time you want to revalidate). If you want a deeper dive into ISR, please reference the Next.js docs and our very own Jeff Everhart's blog post.

ISR Considerations

A scenario to consider when you use ISR is a busy site with lots of visits. Staying with my time stamp example in my code block, I set it to revalidate every 10 seconds. Imagine that I have a very large, busy site and I invoke ISR on 5,000 pages. If I get traffic to all those pages and set to revalidate it every 10 seconds, it will rebuild all of the paths and pages every 10 seconds and you are back to square one with the original issue of overwhelming your WordPress server.

Now, this is just something I want to point out for consideration. For the most part, ISR is still the best option in our opinion. You can set your time stamp to an increased time interval as well as figure out how often each type of data really does change and configure it that way to optimize this approach.

On-Demand ISR Option

Next.js has a feature called On-Demand ISR which is similar to ISR except the difference with this feature is that instead of a time stamp interval and a visit from a user revalidating your stale data, you can update and revalidate the data and content of a page "on-demand" or manually; configuring WordPress to send a webhook to an API route in Next.js when an update to WordPress backend is made.

How to throttle Next.js's concurrency

and export phase in relation to how many threads it is using. Lowering the number of CPU's to reduce concurrent builds will alleviate resources on the server requests when Next.js builds your site. The object in the next.config.js file at the root of the project for this option is as follows:

module.exports = uniformNextConfig({
  experimental: {
    // This is experimental but can
    // be enabled to allow parallel threads
    // with nextjs automatic static generation
    workerThreads: false,
    cpus: 1
  },
});

This is an experimental feature in Next.js. In the config file above, the cpus are set to the value of your limits on your WordPress concurrent connections. This example shows 1. I do recommend you not setting it to the max since you want to leave some for WordPress editors.

The trade-off to this approach is it will slow down the build step, while will reducing the number of pages it tries to build simultaneously. This can help when you WordPress exceeding limitations under the number of requests.

Conclusion & Future Solutions

After seeing some Headless WordPress setups on Next.js and discussing issues within this topic with the community and WPGraphQL, we believe it is optimal to not pre-render every static path and page within getStaticPaths and a Dynamic Route file in Next.js to reduce running into server and GraphQL issues.

Adopting Headless WordPress and using Next.js can be daunting, especially if you have are not familiar with the ecosystem, its issues, and best practices to solve those issues.

Currently, there is no solution on WP that accurately listens to events and communicates with Next.js. Don't worry though! Myself, the Headless WordPress team, and WPGraphQL here at WP Engine are working actively to continue to solve these issues in the very near future so stay tuned!!!!

Hopefully, this blog post on best practice tips of this focused topic was helpful and gave you a better understanding on optimizing Next.js, WPGraphQL, and getStaticPaths! If you want to see this blog post come to life in a live stream video code tutorial, come join Colby, Jason and myself as we refactor according to these best practices here!

As always, hit us up on discord if you have any questions, thoughts, or just want to Jamstoke out with us!

Multi-Lingual Headless WordPress

Fran Agulto — Mon, 04 Jul 2022 20:04:06 +0000

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

Prerequisites

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

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

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

The Polylang WordPress Plug-in

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

Login to your WP Admin and Install Polylang/WPGraphQL extension

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

Check Pretty Permalink Settings

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

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

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

Install Polylang WPGraphQL Extension

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

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

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

Posts/Post Polylang Language Feature

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

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

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

Constructing our GraphQL queries for translated posts

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

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

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

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

Get Next JS Headless WP Starter cloned and running locally

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

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

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

Next.js Internationalized Routing

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

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

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

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

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

Link to filter between languages

need to set up a link we can click on to filter between the languages on posts. Go to components/Navbar.js in the project. You should see this code within the file:

import Link from "next/link";
import { useRouter } from "next/router";
import styles from "../components/Navbar.module.css"

export default function Navbar() {
  const { locale: activeLocale, locales, asPath } = useRouter();

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

  return (
    <div className="container">
      <nav>
        <ul>
          <li>
            <Link href="/">
              <a className={styles.home}>Home</a>
            </Link>
          </li>

        </ul>
        <ul>
          {availableLocales.map((locale) => {
            return (
              <li key={locale}>
                <Link href={asPath} locale={locale}>
                  <a className={styles.toggle}>{locale.toUpperCase()}</a>
                </Link>
              </li>
            );
          })}
        </ul>
      </nav>
    </div>
  );
}

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

import { useRouter } from "next/router";

top of the component and destructure to extract all the locale constant variables that are supported in my application:

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

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

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

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

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

<li>
            <Link href="/">
              <a className={styles.home}>Home</a>
            </Link>
          </li>

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

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

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

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

Apollo Client/GraphQL setup

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

Adding our GraphQL Queries

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

Multi-Lingual Posts on the Home Page

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

export async function getStaticProps({ locale }) {
  const apolloClient = getApolloClient();

  const language = locale.toUpperCase();

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

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

WPGraphQL/Polylang Single Post query

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

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

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

Dynamic Route Page and Single Post Query

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

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

export async function getStaticProps({params, locale}) {
const { postSlug } = params;
const language = locale.toUpperCase();

const apolloClient = getApolloClient();

  const data = await apolloClient.query({
    query: gql`
    query PostBySlug($slug: String!, $language: LanguageCodeEnum!) {
      generalSettings {
        title
      }
      postBy(slug: $slug) {
        id
        content
        title
        slug
        translation(language: $language) {
          id
          slug
          content
          title
          language {
            locale
            slug
          }
        }
      }
    }

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

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

export async function getStaticPaths({ locales }) {
  const apolloClient = getApolloClient();

  const data = await apolloClient.query({
    query: gql`
      {
        posts(first: 10000) {
          edges {
            node {
              id
              title
              slug
            }
          }
        }
      }
    `,
  });

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

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

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

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




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

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

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

Run the demo locally

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

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

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

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

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

Done!! Stoked! 🎉

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

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

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

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