Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including gatsby-source-graphcms with all npm packages installed. Try it out:

var gatsbySourceGraphcms = require("gatsby-source-graphcms")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

gatsby-source-graphcms v0.0.1

Gatsby source plugin for building websites using the GraphCMS as a data source.


XO code style

Source plugin for pulling data into Gatsby from a GraphCMS endpoint.

Working example: @hmeissner/gatsby-graphcms-testing


Once publishied to npm, you will be able to npm install --save gatsby-source-graphcms

For now during alpha-testing phase you need to build the plugin, following the testing steps below.

Gatsby's GraphCMS plugin testing

  1. cd to your Gatsby install, mkdir plugins if it does not exist yet and cd into it.
  2. Your path should now be something like ~/code/graphcms/myKillerGatsbySite/plugins/
  3. git clone
  4. cd gatsby-source-graphcms
  5. yarn && yarn build Swap yarn build for yarn watch in plugin's directory for auto-rebuilding the plugin after you make changes to it—only during development, remember to build the plugin pre-deployment.
  6. Make sure plugin is referenced in your Gatsby config, as in the example below.
  7. From there you can cd ../.. && yarn && yarn develop to test.

Every time you rebuild the plugin, you must restart Gatsby’s development server to reflect the changes in your test environment.


In your gatsby config...

plugins: [
   * Gatsby's data processing layer begins with “source”
   * plugins. Here the site sources its data from the GraphCMS endpoint
    resolve: `gatsby-source-graphcms`,
    options: {
      endpoint: `graphql_endpoint`,
      token: `graphql_token`,
      query: `{
          allArtists {

Use an .env file or set environment variables directly to access the GraphCMS endpoint and token. This avoids committing potentially sensitive data.

Plugin options

endpointindicates the endpoint to use for the graphql connection
tokenThe API access token. Optional if the endpoint is public
queryThe GraphQL query to execute against the endpoint

How to query : GraphQL

Let's say you have a GraphQL type called Artist. You would query all artists like so:

  allArtists {
    picture {
    records {

Current limitations

length must be aliased

If you have a field named length it must be aliased to something else like so: myLength: length. This is due to internal limitations of Gatsby’s GraphQL implementation.

Does not support over 1000 records per __type

A way to automatically paginate and fetch all data is being worked on, but this is a limitation on the backend. See Graphcool Forum — Query without pagination limits and Graphcool Docs — Query API — Pagination

Limitations Note that a maximum of 1000 nodes can be returned per pagination field. If you need to query more nodes than that, you can use first and skip to seek through the different pages. You can also include multiple versions of the same field with different pagination parameter in one query using GraphQL Aliases.

Does not support automatic __meta count association

Related to pagination and 1K limitation, if you want to show an accurate total count of the result set without wanting to aggregate on the client side, especially with large sets, you might want to use the auto-generated meta fields with count. A way to automatically extract the meta fields from query and use createNodeFields to add the meta fields to their corresponding nodes is being worked on.

If in the config query:

allArticles {
__allArticlesMeta {

We would instead move the _allArticlesMeta inside allArticles (as we don’t need nor want any nodes from meta fields) and then query the total articles count like so in the page level:

allArticles {
  __meta {

For now we advise using instead because Gatsby tries to create nodes out of top level fields which does not make sense in this case, bearing in mind pagination limitations described above.

Does not support localization

GraphCMS recently implemented localization, which provides an interesting challenge for the plugin. Work in Gatsby on “GeoIP and Language-based redirects” is ongoing with some really nice extras for those who host with Netlify.


All of the aforementioned limitations are under active discussion and development in the Gatsby channel on the GraphCMS Slack group. Join us!

Other TODOs

  1. Implement support for relationships/embedded fields
  2. Implement mapping feature for transformation plugins, like the MongoDB plugin
  3. Explore schema stitching — Apollo GraphQL Tools Docs, blog post — and graphql-tools


and you?

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free