DEV Community: Dave

How to use 11ty with Headless WordPress

Dave — Sun, 28 Feb 2021 17:08:59 +0000

In this tutorial, we'll learn how to use 11ty with Headless WordPress, and then deploy it to Netlify.

You can see the final project hosted on Netlify at headless-wordpress-11ty.netlify.app, or skip the tutorial altogether and view the Git repo at github.com/thedavedavies/Headless-WordPress-11ty. Lets get started!

What is Eleventy?

Eleventy (or 11ty) is a Static Site Generator, which we can use to fetch our WordPress posts and pages, and then compile the data at build time. This allows us to use WordPress as a Headless CMS, and deploy an entirely static and lightweight site to Netlify. We can get this data from WordPress using either the WordPress REST API, or using a WPGraphQL endpoint. In this tutorial, we'll be using the WordPress REST API.

Why use 11ty with Headless WordPress?

These days there are many great headless Content Management Systems (CMS) and Static Site Generators (SSG) to choose from, so why pick WordPress over any other? I've been working with WordPress for over 10 years, and had a load of established sites I wanted to be able to use the data on. Some of these sites didn't need any extra functionality and so entirely static HTML pages are a perfect solution.

WordPress also has an active and supportive community, with thousands of plugins to help you build any type of website. For sites which need extra functionality, you can use NextJS with Headless WordPress too.

Using the WordPress fetch API

If you've never used Eleventy before, then there's loads of great resources at https://www.11ty.dev. In the meantime, create a fresh project (we'll call ours Headless-WordPress-11ty) and open that new project in your code editor (I'm using VS Code).

Installing Eleventy into our project requires a package.json file. Let's create it with npm init -y. The -y parameter tells npm to skip all the questions and just use the defaults.

npm init -y
npm install --save-dev @11ty/eleventy node-fetch

In that code snippet above, the dependencies we're installing are:

Eleventy -- The Static Site Generator
node-fetch -- We'll use this to fetch our data from the WordPress REST API.

Preparing our 11ty project to fetch data from the WordPress REST API

After installing the Eleventy and node-fetch packages, create a new directory in the root of your project called _data, and inside that new _data folder create a file called posts.js. The _data directory is where all of our global data will be controlled. In our case, that means using the WordPress REST API to hit our endpoint and fetch our posts and pages.

Back in your root directory, create another new directory named _layouts, and inside _layouts create a new file called layout.njk.

What's with the .njk file extension?

The .njk file extension means that we're using Nunjucks as a templating language. You can easily use 10 different templating languages in 11ty (or a mixture of them all) so whilst we're using Nunjucks, if there's a different template language you're more comfortable using, then go ahead and use that.

Finally, back in your root directory again, create 2 new files called index.njk and posts.njk.

Having added these new directories and files, your project should be looking similar to this screenshot:

Creating a .gitignore file

While a .gitignore file isn't essential to testing out the WordPress REST API with 11ty, it's highly recommended for when you want to deploy your site. Here's the .gitignore settings I'm using for this project:


_site/
_tmp/
.DS_Store
node_modules/
package-lock.json
.env*

Step 1: Fetching post data from the WordPress REST API

Now that we've prepared the foundations and set up our base project, let's get writing some code to fetch our posts from WordPress.

Head to your _data/posts.js file, and add the following code:

const fetch = require("node-fetch");

module.exports = async function () {
  console.log("Fetching data...");

  return fetch("https://fake-data.better-wordpress.dev/wp-json/wp/v2/posts")
    .then((res) => res.json())
    .then((json) => json);
};

What does this code do?

Exclusively a browser API, we can't use fetch in NodeJS. Using the node-fetch package brings the ability to use fetch into NodeJS. We're then setting up an asynchronous function, which expects a promise to be returned, which is exactly what's happening when we run return fetch("https://fake-data.better-wordpress.dev/wp-json/wp/v2/posts").

Step 1.5: Testing your fetch

Next, open your package.json file and in your scripts property add the following 2 scripts:

"scripts": {
    "start": "npx @11ty/eleventy --serve",
    "build": "npx @11ty/eleventy"
  },

What does this code do?

The scripts property in your package.json file allows you to run predefined scripts. Once you've added the start and build scripts above, you'll be able to run npm run start to start up a hot-reloading local web server, and npm run build to compile any templates into the output folder (this defaults to _site).

What do we get back from our fetch?

The async function we wrote earlier in _data/posts.js returns to us a JSON object which we can then work with. To confirm that the data is coming back successfully from the WordPress REST API, you can change the final .then in your function to a console.log():

return fetch("https://fake-data.better-wordpress.dev/wp-json/wp/v2/posts")
    .then((res) => res.json())
    .then((json) => console.log(json);

and run your npm run start script in your console. If all goes well with your fetch, then you should see an output similar to the screenshot below, with your JSON data logged out into the console:

Step 2: Creating a layout template

Now that we're successfully fetching our posts from the WordPress REST API, we can start creating a template to show that data.

If you changed your fetch function to console.log(JSON) the JSON data, then make sure you now return it to how it was in Step 1.

In your _includes/layout.njk file, paste in the following code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>{{ posts.title.rendered }}</title>
  </head>
  <body>
    {{ content | safe }}
  </body>
</html>

What does this code do?

Very simply, the code above scaffolds out the HTML we'll use to display our data.

{{ posts.title.rendered }} is the title object that we get back in our JSON object.
Using {{ content | safe }} means that the layout template will populate the content data with the child template's content. Using the safe filter prevents double-escaping the output (this is built into Nunjucks).

Step 3: Creating our index page

Now we get to start seeing content in our browser! In your index.njk file, paste the following code:

---
pagination:
  data: posts
  size: 2
layout: layout.njk
title: "Latest Posts"
---

<ol>
  {%- for item in pagination.items %}
    <li>
      <a href="/posts/{{ item.title.rendered | slug }}">
        {{ item.title.rendered }}</li>
    </a>
  {% endfor -%}
</ol>

<nav>
  <ol>
    <li>
      {% if pagination.href.previous %}
        <a href="{{ pagination.href.previous }}">Previous</a>
      {% else %}Previous{% endif %}
    </li>
    {%- for pageEntry in pagination.pages %}
      <li>
        <a href="{{ pagination.hrefs[ loop.index0 ] }}" {% if page.url == pagination.hrefs[ loop.index0 ] %} aria-current="page" {% endif %}>Page
          {{ loop.index }}</a>
      </li>
    {%- endfor %}
    <li>
      {% if pagination.href.next %}
        <a href="{{ pagination.href.next }}">Next</a>
      {% else %}Next{% endif %}
    </li>
  </ol>
</nav>

What does this code do?

Nunjucks uses front matter, which will be processed by our templates when we build our site. So what does this front matter do?

pagination iterates over our data set and then creates pages for individual chunks of data.
data: posts is taking our _data/posts.js as a data set. The front matter value for data needs to match up with our data file. So, if the file was called _data/pages.js, then our front matter would instead be: data: pages.
size: 2 is telling 11ty to list 2 of our posts before moving onto pagination
layout: layout.njk is telling 11ty to use the layout that we built in Step 2.

With that saved, and npm run start running, you should now be able to see a paginated list of our pre-build posts from WordPress!

Step 4: Creating a template for our single posts

The final task we have to do before launching our site is to create a template for our single posts. Paste the following code into posts.njk:

---
pagination:
    data: posts
    size: 1
    alias: posts
permalink: "posts/{{ posts.title.rendered | slug }}/"
layout: layout.njk
---

<h1>{{ posts.title.rendered }}</h1>
<div class="mainContent">
    {{posts.content.rendered | safe}}
</div>

What does this code do?

The front matter in our posts.njk file is similar to our index.njk, however this time our pagination size is just 1, and we're using an alias in the slug.

11ty provides a number of filters which we can pass into our content. Here, we're using the slug filter to 'slugify' our URL, and the safe filter again to render out the HTML we get back from the WordPress REST API.

Finally we have a fully built (but very much unstyled) site which is populated from our existing WordPress website! Our last task is to deploy this site to Netlify.

Step 5: Hosting our 11ty site with Netlify

Netlify is a powerful serverless hosting platform with an intuitive git-based workflow and a very generous free tier. This means we can deploy our static 11ty site to Netlify, and if you're using Git you can connect Netlify to your Git repo to trigger a rebuild every time you commit.

At this point, it's best practice to remove your API endpoint URLs from your code and use a .env file instead. So let's do that by installing the dotenv package: npm i dotenv. Next, create a .env file in the root of your project. This is where we'll add all of our secret endpoint URLs. If you created a .gitignore file earlier, make sure to have .env* in the file. This will tell git to ignore all .env files.

Open up your .env file, paste in your WordPress REST API endpoint along with a variable to link it to -- i.e.: WORDPRESS_REST_API_URL=https://fake-data.better-wordpress.dev/wp-json/wp/v2/posts

Next, we need to make sure that 11ty knows about our .env file, so create a .eleventy.js file (note the dot at the start of that filename), and paste the following code:

module.exports = function () {
  require("dotenv").config();
};

What does this code do?

The .eleventy.js file holds all our custom site-wide configuration, but for now all we need to pass to it is our dotenv config. You can read more about Eleventy configuration.

Finally in our _data/posts.js file, we can replace our endpoint url with process.env.WORDPRESS_REST_API_URL. We can now safely commit our code to our Git repo without exposing our secret endpoint URLs, or any other API keys you need to keep secret.

Netlify already has a super in-depth blog post on deploying your site, so follow that to get your site up on Netlify. One addition we want to make though, is just before you Deploy your site - click Advanced build settings and add in your env key and value from your local .env file (which hopefully hasn't been committed to your repo).

Finished!

And we're done! We now have a very high level proof-of-concept project to fetch our posts from the WordPress REST API, build them into a static site using Eleventy, then deploy that site to Netlify.

There's plenty more we can do, including styling the site and fetching various pages and other data that the WordPress REST API gives us.

Using NextJS with Headless WordPress

Dave — Sun, 21 Feb 2021 18:29:21 +0000

WordPress is used on over 1.3 billion websites across the world, and it works great as a Headless CMS. NextJS is a framework built on React to give you an amazing amount of features, which you would otherwise need to set up yourself (static rendering, bundling, prefetching etc), and provides super fast and performant websites. Let's combine the two to create a super fast headless WordPress website!

Pre-requisites:

A basic understanding of NodeJS and React

An existing WordPress website with some posts and page

We'll be using Colby Fayock's Next.js WordPress Starter in this walkthrough (https://github.com/colbyfayock/next-wordpress-starter/). This Next.js WordPress Starter project aims to "take WordPress as a headless CMS and use Next.js to create a static experience that can be deployed anywhere."

The Next.js WordPress Starter project allows us to easily pull everything you would normally expect to be in a WordPress website (posts, pages, author listings, global search) and brings it into NextJS through a GraphQL endpoint. The project is actively under development, so watch the repo for further feature updates!

Getting started

WordPress

The Next.js WordPress Starter uses GraphQL, so start by logging into your WordPress website and install WPGraphQL. If you don't have an existing WordPress website, I've set up a dummy project you can use instead at: https://fake-data.better-wordpress.dev.

Next.js WordPress Starter

The quickest way to get started with NextJS for the frontend is by opening your terminal, navigating to the folder you want to start working in, and running:

yarn create next-app -e https://github.com/colbyfayock/next-wordpress-starter

Once that's finished installing, open up your code editor and add an .env.local file to the root of the project. This is where we're going to set up our Environmental Variables, so that NextJS knows where to get our data from.

The Environmental Variable the Starter Project uses is: WORDPRESS_GRAPHQL_ENDPOINT, so I'm using WORDPRESS_GRAPHQL_ENDPOINT="https://fake-data.better-wordpress.dev/graphql" to get some dummy data. You can use this dummy WordPress data too while testing, but don't forget to replace the url with your own WordPress endpoint when you're ready to go live!

Back in your terminal, running yarn dev starts up a development server. This isn't the time to be looking at performance and bundle size of your new NextJS website (a mistake I made when first experimenting with NextJS), although you should always be making sure you ship as small a bundle size as possible. We'll get to that later on.

After running yarn dev in your terminal, you can now open up your browser and see your Headless WordPress site running at: http://localhost:3000.

Congratulations -- you now have a fully headless WordPress website running on the JAM stack, which includes all of you posts, pages and a live search! If you're using my fake data API, then your site should look similar to this screenshot:

Screenshot of data coming from a Headless WordPress installation running on NextJS

At this point, you can start to customise the starter project to look and function exactly how you want it to. And when you're done, it's time to deploy your website for the world to see!

Deploying your NextJS website

Before you run a production build, update your package.json file with your live URL (on line 3). This is the URL which will be passed into your sitemap -- very important for SEO.

Running yarn build in your terminal will actually fetch all of your posts and pages, create a sitemap and an optimised production build of your static website ready to deploy to your server.

After running yarn build, you can then run yarn start to run a local server and test your local production build. This is the perfect time to be looking at your bundle sizes and site speed, as it's a good representation of how your site will respond on a server.

I use vercel.com to deploy better-wordpress.dev. Vercel are the same team who built NextJS, and they have a generous free tier, so it makes perfect sense to deploy it there.

I'm currently working on blog posts explaining how to deploy NextJS to Vercel, Netlify and other hosts -- but in meantime the Vercel docs are pretty great: https://nextjs.org/docs/deployment

Final words

You now have a fully featured and blazingly fast website running on the JAM stack, using NextJS on the frontend and WordPress for your data.