How to Use Wordpress to Power Your Gatsby Site
We have come a long way in terms of how we build websites in the modern age. From coding raw HTML files, to PHP servers, to full JavaScript Web Applications, the web has just gotten better and better. The JAMstack is here and it is awesome. JAMstack is a combination of JavaScript, APIs, and Markdown to build static sites from dynamic content. It has a fantastic Developer Experience, increased security, cheap hosting, and extreme performance. This guide will show you how to setup a production-ready setup, but feel free to skip to the sections that are relevant to your specific needs.
Today we will be building one of these application using Gatsby and Wordpress + WPGraphQL.
Table of Contents
Stack
The following stack may seem intimidating, but each piece is very easy to use with amazing GUIs. This setup is extremely cheap--Only the Wordpress component is not free--And it has the flexibility to be a reliable production deployment.
-
Gatsby App using-gatsby-source-wordpress-experimental
- A super simple Gatsby app powered by Wordpress. Open source!
-
AWS Lightsail for Wordpress
- An easy to use Wordpress as a service. Use whatever your favorite Wordpress hosting service is!
-
Netlify for hosting
- Netlify is the leader in JAMStack hosting. Free!
-
Cloudflare for DNS and HTTPS
- Cloudflare is a great service for DNS. Free!
Setup Wordpress on AWS Lightsail
AWS Lightsail is a great service that allows you to spin up Wordpress installations in seconds, and removes all of the hassel of server administration. You simply checkout your Wordpress image and size, and receive an IP of the running server.
If you have not already, create an AWS account. Navigate to AWS Lightsail
After checkout, you will be able to get your default SSH keys from your
navigating to your account page in the top right of the Lightsail dashboard. You
will need your keys to SSH into your server and install plugins. It may or may
not be called us-east-2.pem
. Make sure you save these somewhere secure.
You can SSH into your Wordpress instance with the following command. Run it inside your favorite terminal emulator:
chmod 400 your-key.pem
ssh -i your-key.pem bitnami@<your-lightsail-ip-address>
Once you are in, grab your username and password from the credentials file in your home folder.
cat bitnami_credentials
Login to your Wordpress admin dashboard that is located at
<your-lightsail-ip-address>/wp-admin
You should now have a terminal logged in to your server and the admin dashboard ready to go in your browser.
Install plugins
We will need to install a few essential plugins, but I will also be installing some luxury plugins.
Essentials
- WPGraphQL
- WPGraphiQL
- WPGatsby
Install:
# Inside your Wordpress server
cd ~/apps/wordpress/htdocs/wp-content/plugins
git clone https://github.com/wp-graphql/wp-graphql
git clone https://github.com/wp-graphql/wp-graphiql
git clone https://github.com/gatsbyjs/wp-gatsby
If you need them
Next, you can totally consider also installing the following plugins for more features
- Advanced Custom Fields
- ACF For WPGraphQL
- Custom Post Types
- Custom Post Types GraphQL
Installing all of the above will give you a beefy, production-ready setup.
Themes
You can use any theme you want on Wordpress -- But remember, this is not going to be reflected to your users. Your users are going to see your Gatsby site, not your Wordpress site. Because of this, I recommend using a headless theme, or even not giving any thought to your Wordpress theme at all.
You can install my headless theme with the following:
cd ~/apps/wordpress/htdocs/wp-content/themes
git clone https://github.com/zeevo/wordpress-headless
# IMPORTANT: Change the href in this theme to reflect where your Gatsby app lives.
vim wordpress-headless/index.php
DNS
DNS is the protocol in which browsers and other application can find the actual IP Address of the server which we want to visit. Think of it as though you are translating people (domains) to phone numbers (ip addresses) in a big phonebook.
I recommend using the following stack of services for DNS/Domain Name-related things:
- Namecheap to buy your domain name
- Cloudflare for domain record configuration
- Netlify for site hosting
We are going to achieve the DNS setup recommended by Netlify, only using Cloudflare's Nameservers instead of Netlify's. There is nothing wrong with using Netlify's, but Cloudflare is free as well and is extremely powerful and flexible.
Essentially we want to use www.yourdomain.com
as our primary domain and
yourdomain.com
seconday. You can think of www.yourdomain
as where your
website lives, and yourdomain.com
as the base domain from which you can setup
other types of DNS records against (mail, etc). The reason for this can be
somewhat technical, but Jen Kagan from Netlify does a great job summarizing this
concisely:
You might think that you could simply configure a CNAME record for the apex domain—point example.com to
.netlify.app—but you shouldn’t! This could severely break other things for you. According to the DNS specification, any domain name that has a CNAME record set cannot have any other DNS records associated with it. This means that if you set up a CNAME record for example.com, you wouldn’t be able to set up MX records—so you wouldn’t be able to receive email at that domain. Want to validate your domain for Google’s webmaster tools? Or perhaps you’d like to use the SPF system to help verify your email sending hosts? You’d need to add a TXT record to the apex domain, but you wouldn’t be allowed to because you already have a CNAME. -- Jen Kagan
Steps you will need to do:
- Purchase your Domain from Namecheap
- Sign up with Cloudflare
- Sign up with Netlify
With your accounts setup, you are ready to move on.
Namecheap
Cloudflare is the leading DNS platform and I recommend using it over your domain registrar's DNS. It is completely free for personal sites. To do this we will need to configure Namecheap to use Cloudflare's Name Servers. At the time of writing this, they are publicly listed as the following:
- blakely.ns.cloudflare.com
- seth.ns.cloudflare.com
If you are using Namecheap, log into your dashboard, select "Manage" on your domain. In the DNS tab, you should be able to select Custom DNS and supply Namecheap with Cloudflare's nameservers.
Save and you are done.
Netlify
Netlify is a fantastic company that is changing the web as we know it. I highly recommend using them to host your Gatsby site. First, we need a site to begin with:
gatsby new gatsby-starter-default https://github.com/gatsbyjs/gatsby-starter-default
Create a Github repository for your new app and push your starter to it.
cd gatsby-starter-default
git remote add origin https://github.com/yourusername/yoursite.git
git add .
git push -u origin master
Log in to Netlify, and select "New site from Git", then select Github, and then your site. After it builds you should get a Netlify URL.
Netlify offers some DNS solutions, but I suggest keep it simple with just your Netlify URL. Mine looks like this:
Netlify Build Hook
Netlify offers the ability to trigger builds through what is called a Build Hook. We can supply Wordpress with our Build Hook, so that it can trigger new builds when content changes.
Create yours and then copy it over to Wordpress. In your Wordpress dashboard, under Settings, there should be a GatsbyJS option that brings you to a place where you can save your Netlify Build Hook.
Netlify Environment
Update your Netlify environment with the location of your Wordpress app. Lots of starters use the key WPGRAPHQL_URL
to track their source endpoint.
Cloudflare
Log in to Cloudflare, and navigate to the DNS tab on your dashboard.
We need to divert traffic to their loadbalancers when people navigate to our domain. We can do this by adding two DNS records in Cloudflare:
- CNAME record: for "www" to our Netlify URL
- A record: for our "base" domain to Netlify's load balancer
Netlify's load balancer is public, and at the time of writing this. It is
104.198.14.52
While you are here, you should also subdomain your Wordpress IP. My Cloudflare looks like this:
We have our wordpress site on wp.yourdomain.com
, and our website is
on www.yourdomain.com
, aswell as just yourdomain.com
(no "www")
Putting it all together
You can almost think of the relationship between these two technologies as our "frontend" being Gatsby and our "backend" being Wordpress. But our frontend will be completely static. How is this possible? Well, Gatsby will query our Wordpress app for content using GraphQL, and generate a blazing-fast static site that we can host cheaply. When content changes in Wordpress (new Post, new Comment), we will simply rebuild our site-- Giving the illusion that we're truly dynamic, but reaping all the rewards of static hosting.
Let's use a Gatsby starter.
gatsby new my-site https://github.com/TylerBarnes/using-gatsby-source-wordpress-experimental
cd my-site
This project uses env
files to configure the Wordpress GraphQL endpoint. Let's create one for development.
echo "WPGRAPHQL_URL=https://wp.yourdomain.com/graphql" > .env.development
Now we can build it and see the content from our Wordpress app being rendered using Gatsby and React. GraphQL API requests are being sent at build time, and a static site (HTML, CSS, JS) will be generated.
gatsby develop
The stock bitnami Wordpress app comes with a sample page. Try navigating to http://localhost:8000/sample-page/
The starter Gatsby app is a template. Build something great with it!