In Part 1 of this series, we determined that we’d migrate our client’s website from WordPress to a JAMstack. We now needed:

  1. A static site generator
  2. A headless CMS
  3. A hosting provider

1. Static site generator: Gatsby

The first thing we needed to figure out is what static site generator we’d work with. We went with Gatsby, because it:

  • Supports React, and is open source
  • Includes a large developer community to support it, and plugins for additional functionality
  • Leverages GraphQL as a unifying API for the data layer
  • Loads only the critical HTML, CSS, data, and JavaScript, which improves load time
  • Prefetches resources for other pages, another speed enhancement; clicking around the site feels incredibly fast

Gatsby’s built-in performance optimizations hit many of our technical goals: speed, SEO, stability, and performance.

2. Headless CMS: Contentful

Traditional CMSs (WordPress, Drupal, etc.) are tightly coupled with the presentation layer, and put restrictions on the technology stack used for development and deployment. This rigidity has given rise to a new class of “headless” CMSs, which lifts these restrictions by decoupling content management from presentation. Instead, they focus solely on APIs for both content management and delivery. The majority of these headless CMSs are hosted externally, which takes the burden of managing infrastructure for content management and delivery off of your team. This was especially important for our client, who didn’t have an on-site technical team.

(As an aside: WordPress can be leveraged as a headless CMS using their REST API — we did just that a few years ago for WBUR — but you’d need to host the WordPress editor and content database along with your static site.)

Enter Contentful, an industry leader in the headless CMS space. It provides:

  • RESTful APIs; client SDKs in all popular languages
  • Multi-language support
  • Clear, detailed developer documentation
  • External validation by well-known customers.
    This is really important with an externally hosted CMS. If the company hosting your CMS goes down, your site’s content goes down with it. Knowing that other, larger companies use Contentful gave us peace of mind.
  • An editor UI that is clean and easy-to-understand
  • Content migration APIs that allow us to write scripts that manage our separate staging and production spaces
  • The ability to customize previews for each content type, making the CMS feel integrated into our site
  • The capacity to create custom field types called Extensions

However, it does have limitations when it comes to creating custom fields for more complex landing page layouts. We were able to create more “content types” to compensate for the missing field functionality.

Side note: A cheaper (but less mature) alternative to Contentful

Contentful has recently changed their pricing. Their small plan is now $189 (up from $39/month) and caps the number of content types you can have on each plan.

A much cheaper alternative to Contentful is Prismic. With comparable plans starting at $9/month, it has more flexibility with content modeling — but also these drawbacks:

  • Lack of flexible multi-environment workflows
  • Inability to create custom field types
  • Less mature-looking UI

How Contentful and Gatsby Work Together

We mentioned above that Gatsby leverages GraphQL as a unifying API for your data layer. While Contentful does have a GraphQL Delivery API in the works, as of this writing it’s not quite ready for production use.

Fortunately, Gatsby’s source plugin architecture enables developers to wrap any data source with a GraphQL API. There are source plugins available for several popular backends including WordPress, Drupal, and, of course, Contentful. They all work the same way — they source data from their respective APIs and use helper functions provided by Gatsby to transform it into a GraphQL API that is queryable from React.

All of this happens at build time, which is necessary in order to generate a static site. This approach is particularly nice for source APIs that implement rate limiting or incur usage charges, as API calls only happen at build time and not for each page view. It also means that if your backend goes down, your site will remain up — builds will fail until the API comes back online, but your end users will be blissfully unaware.

3. Hosting: Netlify

To host our static site, we chose Netlify, one of the leading static site hosting services. Netlify gave us:

  • Continuous deployment via a build command whenever we pushed updates to the given Github repository
  • Webhooks to use with Contentful, so that our site would autodeploy when editors changed content
  • Links to live build previews of a pull request, making it easy for others to review any changes
  • Convenient rollbacks to revert to a previously-published version at the click of a button
  • An automatically-provisioned Let’s Encrypt certificate for SSL
  • Redirect and rewrite rules that are simple to configure in a plain text file
  • Affordable, flexible pricing that starts at $0 and increases as features are built

In Part 3 of this series we’ll share our experience working with this combination of technologies.

PS: Do projects like this interest you? Upstatement’s hiring.

Bea Huang is an engineering manager at Upstatement.