Installation
npm install gatsby-source-buttercms --save
yarn add gatsby-source-buttercms
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