Registry / devops / gatsby-graphql-source-toolkit

gatsby-graphql-source-toolkit

library2.0.4jsnpmunverified

A toolkit for building custom Gatsby source plugins that fetch data from remote GraphQL APIs. Current stable version: 2.0.4. This package is in maintenance mode pending a replacement. Unlike gatsby-source-graphql, it correctly sources nodes into Gatsby's data layer, enabling caching, incremental builds, and Gatsby Preview. Features include automatic pagination, concurrent data fetching, delta change tracking, and schema customization. Ships TypeScript definitions. Peer dependency on Gatsby v3/v4/v5.

devops

npm install gatsby-graphql-source-toolkit

package ↗

INSTALL

IMPORT

SIG · GATSBY-GRAPHQL-SOU

gatsby-graphql-source-toolkit

devopsjavascriptv2.0.4

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.

sourceAllNodes

✓ import { sourceAllNodes } from 'gatsby-graphql-source-toolkit'

✗ import sourceAllNodes from 'gatsby-graphql-source-toolkit'

Named export, not default. ESM module.

buildNodeDefinitions

✓ import { buildNodeDefinitions } from 'gatsby-graphql-source-toolkit'

✗ const buildNodeDefinitions = require('gatsby-graphql-source-toolkit').buildNodeDefinitions

CommonJS require is valid but using named import is preferred.

createDefaultQueryExecutor

✓ import { createDefaultQueryExecutor } from 'gatsby-graphql-source-toolkit'

Returns a query executor object; typically passed to other toolkit functions.

loadSchema

✓ import { loadSchema } from 'gatsby-graphql-source-toolkit'

✗ import { loadSchema } from 'graphql'

This is a custom function that fetches the remote schema, not the graphql-js loadSchema.

Shows how to configure and use the toolkit in a Gatsby source plugin: set up executor, load schema, define node types, compile queries, and source nodes.

const { sourceAllNodes, buildNodeDefinitions, createDefaultQueryExecutor, loadSchema, compileNodeQueries, createSchemaCustomization } = require('gatsby-graphql-source-toolkit'); exports.sourceNodes = async (gatsbyApi) => { const executor = createDefaultQueryExecutor('https://api.example.com/graphql'); const schema = await loadSchema(executor); const nodeDefs = await buildNodeDefinitions([ { remoteTypeName: 'Post', queries: ` query LIST_POST { posts { id title } } query GET_POST($id: ID!) { post(id: $id) { id title } } ` } ]); const queries = compileNodeQueries({ schema, gatsbyApi, nodeDefs }); await sourceAllNodes({ gatsbyApi, schema, executor, queries }); }; exports.createSchemaCustomization = (gatsbyApi) => { const nodeDefs = /* same as above */; createSchemaCustomization({ gatsbyApi, nodeDefs }); };

Debug

Known issues

deprecatedThis package is in maintenance mode and will be replaced by a 'swiss army knife' solution. New projects should consider alternatives.

fix

Monitor the Gatsby repository for the replacement package; for now it works but no new features will be added.

affects: >=2.0.0

breakingGatsby v3/v4/v5 are peer dependencies. Version 2.0.0 dropped support for Gatsby v2.

fix

Upgrade Gatsby to v3, v4, or v5, or pin to an older version of the toolkit (v1.x).

affects: >=2.0.0 <3.0.0

gotchaThe toolkit does not provide a ready-to-use source plugin. It is a library to build custom source plugins. Beginners may expect it to work out of the box.

fix

Refer to the examples repository (https://github.com/vladar/gatsby-graphql-toolkit-examples) for usage patterns.

affects: all

gotchaAutomatic pagination relies on the remote schema following a specific pattern (e.g., edges/node). Non-standard pagination may require a custom PaginationAdapter.

fix

Implement a custom adapter; see the README section on Custom Pagination Adapter.

affects: all

Errors

Common errors & fixes

TypeError: Cannot read property 'typeMap' of undefined

loadSchema was called before setting up the executor or the schema is unavailable.

fix

Ensure createDefaultQueryExecutor is called with a valid URL and the executor is passed correctly to loadSchema.

Error: "compiledQueriesDir" is required

Missing configuration option when compiling queries without providing an explicit directory.

fix

Pass compiledQueriesDir in the options object, or ensure the Gatsby project root is set correctly.

Error: Cannot find module 'gatsby/graphql'

Incorrect import path for Gatsby's graphql module. The toolkit expects Gatsby to be installed as a peer dependency.

fix

Run npm install gatsby or ensure Gatsby is in your project's dependencies.

Upgrade

Version history

2.0.4latest on npm

Audit

Dependencies

gatsbyrequiredPeer dependency; must be installed with a compatible version (^3.0.0 || ^4.0.0 || ^5.0.0)

Agent activity

8 hits · last 30 days

node

Resources

packagegatsby-graphql-source-toolkit ↗