gatsby-source-graphcms

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

Example: @GraphCMS/gatsby-graphcms-example

Install

yarn add gatsby-source-graphcms or npm i gatsby-source-graphcms
Make sure plugin is referenced in your Gatsby config, as in the example below
gatsby develop

Testing plugin contributions

cd to the Gatsby install you want to test your changes to the plugin code with, or clone @GraphCMS/gatsby-graphcms-example
If you cloned the example or previously installed the plugin through yarn or npm, yarn remove gatsby-source-graphcms or npm r gatsby-source-graphcms
mkdir plugins if it does not exist yet and cd into it
Your path should now be something like ~/code/graphcms/myKillerGatsbySite/plugins/
git clone https://github.com/GraphCMS/gatsby-source-graphcms.git
cd gatsby-source-graphcms
yarn or yarn && yarn watch in plugin’s directory for auto-rebuilding the plugin after you make changes to it—only during development
Make sure plugin is referenced in your Gatsby config, as in the example below
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.

Usage

In your gatsby config...

plugins: [
  {
    resolve: `gatsby-source-graphcms`,
    options: {
      endpoint: `graphql_endpoint`,
      token: `graphql_token`,
      query: `{
          allArtists {
            id
            name
          }
      }`,
    },
  }
],

Gatsby’s data processing layer begins with “source” plugins, configured in gatsby-config.js. Here the site sources its data from the GraphCMS endpoint. Use an .env file or set environment variables directly to access the GraphCMS endpoint and token. This avoids committing potentially sensitive data.

Plugin options


endpoint	indicates the endpoint to use for the graphql connection
token	The API access token. Optional if the endpoint is public
query	The 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 {
    id
    name
    slug
    picture {
      id
      url
      height
      width
    }
    records {
      id
      title
    }
  }
}

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 graph.cool 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 {
  id
}
__allArticlesMeta {
  count
}

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 {
    count
  }
}

For now we advise using this.props.data.articles.edges.length 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.

Discussion

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

Other TODOs

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

Contributors

@redmega Angel Piscola
@rafacm Rafael Cordones
@hmeissner Hugo Meissner
@rdela Ricky de Laveaga

…and you?

jaeseungyum / gatsby-source-graphcms Goto Github PK