Skip to main content

Installation

npm install gatsby-source-buttercms --save

Configuration

Add the plugin to your gatsby-config.js:
module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-buttercms",
      options: {
        authToken: process.env.BUTTER_CMS_API_KEY,
        // Optional: specify page types to source
        pageTypes: ["landing_page", "product_page"],
        // Optional: specify collection keys to source
        collections: ["faq", "navigation"],
        // Optional: enable preview mode for draft content
        preview: false,
        // Optional: specify locales
        locales: ["en", "fr"],
        // Optional: specify levels of nested references
        levels: 2,
      },
    },
  ],
};
Store your API token in a .env file and reference it via process.env to keep it out of version control.

Querying Content

After sourcing, all ButterCMS content is available in Gatsby’s GraphQL layer.

Pages

query {
  allButterPage(filter: { page_type: { eq: "landing_page" } }) {
    nodes {
      id
      slug
      fields {
        headline
        hero_image
        body_content
      }
    }
  }
}

Collections

query {
  allButterCollection(filter: { key: { eq: "faq" } }) {
    nodes {
      key
      fields {
        question
        answer
      }
    }
  }
}

Blog Posts

query {
  allButterPost {
    nodes {
      id
      slug
      title
      summary
      published
      author {
        first_name
        last_name
      }
      categories {
        name
        slug
      }
    }
  }
}

Example Page Component

import React from "react";
import { graphql } from "gatsby";

export default function LandingPage({ data }) {
  const page = data.butterPage;

  return (
    <main>
      <h1>{page.fields.headline}</h1>
      <img src={page.fields.hero_image} alt="Hero" />
      <div dangerouslySetInnerHTML={{ __html: page.fields.body_content }} />
    </main>
  );
}

export const query = graphql`
  query($slug: String!) {
    butterPage(slug: { eq: $slug }, page_type: { eq: "landing_page" }) {
      slug
      fields {
        headline
        hero_image
        body_content
      }
    }
  }
`;

Programmatic Page Creation

Generate pages from ButterCMS content in gatsby-node.js:
exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions;

  const result = await graphql(`
    {
      allButterPage(filter: { page_type: { eq: "landing_page" } }) {
        nodes {
          slug
        }
      }
    }
  `);

  result.data.allButterPage.nodes.forEach(({ slug }) => {
    createPage({
      path: `/${slug}`,
      component: require.resolve("./src/templates/landing-page.js"),
      context: { slug },
    });
  });
};

Resources

GitHub Repository

View source code, report issues, and contribute

npm Package

Package details and version history