Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Official Plugin
View plugin on GitHub


Persists Gatsby GraphQL schema and fragments to the .cache directory, as well as a GraphQL Config file to enable full-featured tooling for:


npm install gatsby-plugin-graphql-config

How to use

First, add it to your plugin configuration:

// In your gatsby-config.js

plugins: [`gatsby-plugin-graphql-config`]

Simplest setup

If you are able to configure your tools to seek a different basePath for loading GraphQL Config, point them to .cache directory.

Manual setup for repositories with no other GraphQL projects

If your project is only a Gatsby project, you can place a graphql.config.js file at the root of your Gatsby project like this:

// <my project>/graphql.config.js

module.exports = require("./.cache/graphql.config.json")

If it’s in a subdirectory such as a site/ folder, you would use this:

// <my project>/graphql.config.js

module.exports = require("./site/.cache/graphql.config.json")

Manual setup for repositories with multiple GraphQL projects

If your repository has multiple GraphQL projects including Gatsby, you will want a config similar to this at the root:

// <my project>/graphql.config.js

module.exports = {
  projects: {
    site: require("packages/site/.cache/graphql.config.json"),
    server: {
      schema: "packages/server/src/**/*.{graphql,gql}",
      documents: "packages/server/src/queries/**/*.{ts,tsx,js,jsx}",

How it works

It writes out these files to the Gatsby .cache directory:

  • schema.graphql - a complete representation of the schema, including plugins
  • fragments.graphql - all user, plugin and gatsby-core provided fragments in one file
  • graphql.config.json - a graphql-config@3 compatible config file with absolute file resolutions
© 2023 Gatsby, Inc.