Setup Issues With ButterCMS and Gatsby

Publication Date | March 02, 2019
Last Updated | June 25, 2020


I've been trying out ButterCMS with Gatsby for about a week now. It's a pleasure once it's setup, but there are a few hiccups that I found missing in scattered documentation.

  1. Due to an issue in Gatsby and using to set HTML, where dangerouslySetInnerHTML doesn't work on production builds,
    should be used instead. The documentation here uses

    to set HTML. If using

    upon a page refresh, you'll find an empty page. Instead use the below to set HTML.

<div dangerouslySetInnerHTML={{ __html: body }} />
  1. If you are following documentation from, I'd recommend to remove categories from the query below
  try {
    posts = await graphql(`
        allButterPost {
          edges {
            node {
              categories {
              author {

If categories is not populated on ANY blog post on ButterCMS, the GraphQL query will have a cryptic error! Your options are to

  • always have categories populated in all your blog posts
  • or omit categories from the query itself and don't use categories in GatsbyJS
  • Your dynamically created pages won't have the proper CSS on a refresh (or from a fresh external link). You'll probably need to create a gatsby-browser.js in the base level of your base directory to import your CSS for all your dynamic blog post pages. Otherwise dynamically created pages won't have CSS applied (except for certain CSS-in-JS toolkits).

In short, after your initial setup, make sure to refresh blog pages after a production deploy. Hopefully you won't run into the same issues I had! Good luck!

Contact: Please feel free to email me at [email protected] or tweet @shekkery.
Friendly Request: Writing quality articles is hard. Getting traffic is even harder. Thank you for sharing!

Like Software Engineering, Machine Learning or Meta-Learning? Get new posts before they're released. No spam ever, promise.