Community Plugin
View plugin on GitHub
See starters using this

IMPORTANT

This repo is now deprecated. Please see the new home of the Cosmic Gatsby source plugin at https://www.npmjs.com/package/@cosmicjs/gatsby-source-cosmic.

Gatsby Source for Cosmic

Source plugin for fetching data into Gatsby from Cosmic. Cosmic offers a Headless CMS for your Gatsby website.

Install

npm install --save gatsby-source-cosmicjs

How to use

Log into your Cosmic account to get your bucketSlug and apiAcecss keys.

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-source-cosmicjs`,
    options: {
      bucketSlug: ``, // Get this value in Bucket > Settings
      objectTypes: [`posts`],
      // If you have enabled read_key to fetch data (optional).
      apiAccess: {
        read_key: ``, // Get this value in Bucket > Settings
      },
      localMedia: true, // Download media locally for gatsby image (optional)
      limit: 1000, // The number of Objects to fetch on each request (optional)
      debug: false, // Optional: will output details about the API requests to Cosmic
    }
  },
]

Advanced configuration

For more control over how content is sourced from Cosmic, you can provide object type overrides in the plugin configuration. This can be useful if you are coming up against API limits, or are trying to performance tune your builds. Use at your own risk!

Get Objects API documentation

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-source-cosmicjs`,
    options: {
      bucketSlug: ``, // Get this value in Bucket > Settings
      objectTypes: [
        // Basic usage: define objectType as a string
        `posts`, 
        // Advanced usage: define objectType as an object
        { 
          type: `news`, // required
          params: { // any valid API parameter can be used. YMMV!
            hide_metafields: true, // hides metafields, which can get pretty large. You should only need metadata
            limit: 100, // this will override the limit only for this object type
          },
        },
      ],
      // If you have enabled read_key to fetch data (optional).
      apiAccess: {
        read_key: ``, // Get this value in Bucket > Settings
      },
      localMedia: true, // Download media locally for gatsby image (optional)
      limit: 1000, // The number of Objects to fetch on each request (optional)
      debug: false, // Optional: will output details about the API requests to Cosmic
    }
  },
]

Debugging

Use the debug: true flag in your config to get more information about the build. This will provide:

  • Exact Cosmic API endpoint being used for each object type
  • Response size returned from Cosmic for the request

How to query and filter (Not Localized)

You can query the nodes created from Cosmic with the following:

{
  allCosmicjsPosts {
    edges {
      node {
        id
        slug
        title
      }
    }
  }
}

and you can filter specific node using this:

{
  cosmicjsPosts(slug: {eq: ''}) {
    id
    slug
    title
  }
}

How to use Gatsby Image

if localMedia=true in plugin config, you can use Gatsby Image.

Note: gatsby-image and gatsby-source-filesystem plugins are required.

{
  allCosmicjsPosts {
    edges {
      node {
        slug
        metadata{
          hero {
            local {
              childImageSharp {
                fluid(quality: 90, maxWidth: 1920) {
                  ...GatsbyImageSharpFluid_withWebp
                }
              }
            }
          }
        }
      }
    }
  }
}

Read gatsby-image documentation here here.

How to query (Localized)

{
  allCosmicjsPosts(filter: {locale: {eq: "en"}}, sort: {fields: [published_at], order: DESC}) {
    edges {
      node {
        id
        slug
        title
        locale
      }
    }
  }
}

Starters

Install the Cosmic Gatsby starter:

npm i cosmicjs -g
cosmic init gatsby-starter
cd gatsby-starter
cosmic start

Install the Cosmic Gatsby localization starter:

npm i cosmicjs -g
cosmic init gatsby-starter
cd gatsby-localization-starter
cosmic start