Setup Issues With ButterCMS and Gatsby

References

• https://buttercms.com/blog/how-to-use-gatsby-with-a-headless-cms
• https://www.gatsbyjs.org/packages/gatsby-source-buttercms/
• https://www.gatsbyjs.org/docs/sourcing-from-buttercms/#blog-home-page

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 <p> to set HTML, where dangerouslySetInnerHTML doesn't work on production builds, <div> should used instead. The documentation here uses <p> to set HTML. If using <p> upon a page refresh, you'll find an empty page. Instead use the below to set HTML. 

<div dangerouslySetInnerHTML={{ __html: body }} />

2) If you are following documentation from https://www.gatsbyjs.org/docs/sourcing-from-buttercms/, I'd recommend to remove categories from the query below

  try {
    posts = await graphql(`
      {
        allButterPost {
          edges {
            node {
              id
              seo_title
              slug
              categories {
                name
                slug
              }
              author {
                first_name
                last_name
                email
                slug
                profile_image
              }
              body
            }
          }
        }
      }
    `)

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

3. 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!