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, <div> should be used instead. The documentation here uses <p> 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!

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.