Registry / devops / gatsby-plugin-schema-snapshot

gatsby-plugin-schema-snapshot

library4.16.0jsnpmunverified

Creates a snapshot of the Gatsby GraphQL schema by saving minimal type definitions to a file and re-creating the schema from the snapshot during bootstrap. It adds the @dontInfer directive to all top-level types, effectively locking down the schema for production stability. Version 4.16.0 requires Gatsby v5.0.0-next as a peer dependency. This plugin is part of the Gatsby monorepo and is updated alongside Gatsby releases. It is intended for projects that want to prevent schema changes from being introduced unexpectedly, offering control via include/exclude lists and an optional update flag. The plugin is stable but rarely updated independently.

devops

npm install gatsby-plugin-schema-snapshot

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GATSBY-PLUGIN-SCHE

gatsby-plugin-schema-snapshot

devopsjavascriptv4.16.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

gatsby-plugin-schema-snapshot

✓ module.exports = { plugins: ['gatsby-plugin-schema-snapshot'] }

✗ import gatsbyPluginSchemaSnapshot from 'gatsby-plugin-schema-snapshot'

This is a Gatsby plugin, not a direct import. It is used in gatsby-config.js as a CommonJS require. ESM import is not supported for config.

gatsby-plugin-schema-snapshot options

✓ { resolve: 'gatsby-plugin-schema-snapshot', options: { path: 'schema.gql' } }

✗ { plugins: [ 'gatsby-plugin-schema-snapshot', { path: 'schema.gql' } ] }

Options must be passed inside the plugin configuration object with a 'resolve' key. The short string form does not accept options.

update option

✓ options: { update: true }

✗ options: { update: 'true' }

The 'update' option expects a boolean, not a string. It is recommended to use an environment variable like process.env.GATSBY_UPDATE_SCHEMA_SNAPSHOT to control updates.

Configures the plugin in gatsby-config.js to lock the GraphQL schema, excluding types from a specific source plugin, and enabling updates via an environment variable.

// gatsby-config.js module.exports = { plugins: [ { resolve: `gatsby-plugin-schema-snapshot`, options: { path: `schema.gql`, exclude: { plugins: [`gatsby-source-npm-package-search`], }, update: process.env.GATSBY_UPDATE_SCHEMA_SNAPSHOT || false, }, }, ], } // To regenerate the snapshot: // GATSBY_UPDATE_SCHEMA_SNAPSHOT=true gatsby develop

Debug

Known issues

breakingRequires Gatsby v5.0.0-next or later. Using with older Gatsby versions will cause errors.

fix

Upgrade Gatsby to v5.0.0-next or later, or use an older version of the plugin.

affects: <5.0.0-next

gotchaIf 'update' is set to false (or omitted), the plugin will NOT overwrite an existing snapshot file. This can cause stale schemas in production.

fix

Set 'update: true' or use an environment variable to regenerate the snapshot when needed.

affects: >=3.0.0

gotchaBy default, internal and built-in types are excluded. Manually excluding required types may break the GraphQL schema.

fix

Ensure excluded types are not required for the project's queries. Use 'include' to force inclusion of necessary types.

affects: >=3.0.0

deprecatedPlugin is in maintenance mode; not actively developed. New features may not be added.

fix

Consider alternative schema locking strategies or contribute to the plugin.

affects: >=4.0.0

gotchaThe plugin uses CommonJS and cannot be imported as ESM in gatsby-config.js. Using 'import' will fail.

fix

Use 'module.exports' and CommonJS require syntax in gatsby-config.js.

affects: all

Errors

Common errors & fixes

Error: Cannot find module 'gatsby-plugin-schema-snapshot'

Plugin not installed or missing from package.json dependencies.

fix

Run: npm install gatsby-plugin-schema-snapshot

Error: Invalid plugin options passed to gatsby-plugin-schema-snapshot

Options object is malformed or missing the 'resolve' key.

fix

Use the correct format: { resolve: 'gatsby-plugin-schema-snapshot', options: { ... } }

The plugin "gatsby-plugin-schema-snapshot" is incompatible with your version of Gatsby.

Gatsby version is too old (e.g., v4) to meet peer dependency requirement.

fix

Upgrade Gatsby to v5.0.0-next or later.

ENOENT: no such file or directory, open 'schema.gql'

Attempting to read a snapshot file that doesn't exist yet.

fix

First generate the snapshot by running with update=true: GATSBY_UPDATE_SCHEMA_SNAPSHOT=true gatsby develop

Upgrade

Version history

4.16.0latest on npm

Audit

Dependencies

gatsbyrequiredPeer dependency: requires Gatsby v5.0.0-next or later to work.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/gatsbyjs/gatsby ↗

packagegatsby-plugin-schema-snapshot ↗

homepagehttps://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-schema-snapshot#readme ↗