Gatsby Starter ButterCMS is a starter template (boilerplate) that pairs the Gatsby static site framework with the ButterCMS headless CMS, giving developers a pre-configured Gatsby site that pulls content from ButterCMS.
What is Gatsby Starter ButterCMS?
Gatsby Starter ButterCMS is a boilerplate project created by ButterCMS that wires a Gatsby site to a ButterCMS backend. It takes your ButterCMS API token and content configuration as input and produces a static Gatsby site with pages and blog content pulled from the CMS. The template runs on the Gatsby framework (Node.js) and is distributed as a public GitHub repository. It is an example use case, not a product, and the README states it will not be actively maintained; ButterCMS directs users to its official starters for currently maintained integrations.
Key Features
- Gatsby framework — Built on Gatsby, a React-based static site generator, with the standard file structure: src, gatsby-config.js, gatsby-node.js, gatsby-browser.js, gatsby-ssr.js, and package.json.
- ButterCMS integration — Uses the gatsby-source-buttercms plugin to fetch content; requires an authToken from your ButterCMS dashboard.
- Content fields and collections — Supports pulling collection keys via contentFields configuration, with a test mode flag to view draft content.
- Page types — Lets you define page type keys to pull structured pages from ButterCMS.
- Locale support — Can pull content in multiple locales (such as en, es, fr) if locales are configured in your ButterCMS account.
- Preview mode — The plugin supports a preview flag to return draft content during development.
- GraphiQL explorer — During gatsby develop, a GraphQL playground is available at localhost:8000/___graphql for querying fetched CMS data.
- Deployment options — Includes instructions for Gatsby Cloud (using the BUTTER_CMS_TOKEN environment variable) and a one-click Netlify deploy button.
Who is it for?
- Gatsby developers — who want a reference implementation of connecting Gatsby to ButterCMS, including the plugin setup and configuration.
- Content teams — evaluating ButterCMS as a headless CMS; the starter gives them a running site with a structure they can replace.
- Agencies and freelancers — building marketing sites or blogs for clients who need a CMS workflow with a static frontend.
What can you do with it?
- Launch a blog: Use the starter to scaffold a blog whose posts are managed in ButterCMS, then deploy to Netlify or Gatsby Cloud.
- Build a corporate site: Configure page types and content fields in gatsby-config.js to render landing pages, about pages, and other structured content from the CMS.
- Prototype ButterCMS integration: Quickly test how ButterCMS collections and locales behave inside a Gatsby project before committing to an architecture.
How does it work?
The setup flow is: 1) create a new Gatsby site with the npx gatsby new command using this repository; 2) add your ButterCMS API token and specify content fields, page types, and locales in the gatsby-config.js file; 3) run gatsby develop to start a local server at localhost:8000 and query content via GraphiQL. The plugin fetches ButterCMS content at build time and exposes it to Gatsby's GraphQL layer for page queries.
FAQ
Is this starter actively maintained?
No. The README states this project was created as an example use case and will not be actively maintained. ButterCMS recommends using its official Gatsby starter from the starters page, which is fully integrated with dynamic sample content.
Do I need a ButterCMS account?
Yes. The template requires a ButterCMS API token from your dashboard. Sample content is created automatically when you sign up for a free trial.
What do I configure in gatsby-config.js?
You need to set the authToken, and optionally specify contentFields keys (for collections), pageTypes keys (for pages), locales, and a preview flag. The plugin options are documented in the starter README.
How do I deploy this to Netlify?
Use the deploy button in the README, which points to the repository and triggers a Netlify import. For Gatsby Cloud, set the BUTTER_CMS_TOKEN environment variable to your Read API Token.
