Understanding the Gatsby Redux Store and GraphQL Data Layer Relationship

Gatsby's Redux store serves as the single source of truth for the entire build process, housing the GraphQL schema, node data, and query state that the GraphQL runner consumes directly during execution.

In the gatsbyjs/gatsby codebase, the relationship between state management and data fetching is tightly coupled through a centralized Redux architecture. This article explores how the Gatsby Redux store and GraphQL data layer relationship enables the framework to manage complex build processes, from sourcing nodes to executing page queries, without maintaining separate data caches.

The Redux Store as the Central State Container

Gatsby initializes its Redux store via createStore() in packages/gatsby/src/redux/index.ts. This store becomes the authoritative record for all build-time information, including site configuration, plugin data, and the complete node collection.

All internal subsystems subscribe to this store and communicate through dispatched actions. When a plugin calls createNode or createTypes, these actions flow through the store's reducers and immediately update the global state.

Schema Storage in the Global State

After the schema construction phase completes via buildSchema, the resulting GraphQLSchema object is stored in store.getState().schema. The schema customization composer resides at store.getState().schemaCustomization.composer. This synchronization is visible in packages/gatsby/src/utils/worker/child/schema.ts, where the system dispatches actions to populate these state properties during the build process.

How the GraphQL Runner Consumes Store State

The GraphQL runner does not maintain its own copy of the schema or node data. Instead, it receives the Redux store as its primary dependency and queries state on demand.

In packages/gatsby/src/query/index.ts, the runner is instantiated lazily:

if (!graphqlRunner) {
  graphqlRunner = new GraphQLRunner(store, { graphqlTracing })
}

This pattern ensures the runner always accesses the current schema and node map from store.getState().nodes and store.getState().schema.

Query Execution and Data Persistence

When executing page or static queries, the GraphQLRunner resolves fields by reading directly from store.getState().nodes. The query results are then stored back into the Redux state under state.graphqlState, making them available to subsequent build steps and plugins.

This circular flow ensures data consistency: plugins dispatch actions to mutate nodes, the store updates, and the next query execution sees those changes immediately without requiring manual cache invalidation.

Plugin APIs and Store Interactions

Plugin lifecycle methods such as sourceNodes, createPages, and createResolvers interact with the GraphQL data layer exclusively through the Redux store's action system.

When a plugin defines new types via createTypes in gatsby-node.js, it triggers an action that updates store.state.schema:

// In gatsby-node.js
exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions
  createTypes(`
    type Author implements Node {
      name: String!
      avatar: File @fileByRelativePath
    }
  `)
}

The implementation in packages/gatsby/src/utils/create-schema-customization.ts processes these dispatches, ensuring schema modifications are immediately reflected in the global state for the next query execution.

Key Implementation Files

Understanding the Gatsby Redux store and GraphQL data layer relationship requires examining these critical source files:

• packages/gatsby/src/redux/index.ts – Contains createStore() and root reducer definitions that establish the initial state structure, including schema, nodes, and graphqlState.

• packages/gatsby/src/query/query-runner.ts – Implements the GraphQLRunner class, which receives the store instance and reads schema and node data during query execution.

• packages/gatsby/src/services/build-schema.ts – Orchestrates schema construction and dispatches actions.createTypes to populate store.state.schema.

• packages/gatsby/src/utils/create-schema-customization.ts – Provides plugin APIs like createTypes and createFieldExtension that mutate schema state through Redux actions.

• packages/gatsby/src/utils/source-nodes.ts – Handles actions.createNode calls that populate store.state.nodes with sourced data.

• packages/gatsby/src/state-machines/data-layer/actions.ts – Contains internal logic for accessing node data directly from the store, used by the data layer state machine.

• packages/gatsby/src/utils/worker/child/schema.ts – Manages schema serialization in worker processes and dispatches schema updates to the store.

Summary

• The Redux store is the single source of truth for all build-time data in Gatsby, including the GraphQL schema and node collections.
• The GraphQL runner instantiates with the store as its primary argument and reads live state during query execution.
• Schema and node data persist in store.getState().schema and store.getState().nodes, ensuring all plugins access consistent data.
• Query results are stored in state.graphqlState for consumption by subsequent build steps.
• Plugin APIs dispatch Redux actions to mutate the data layer, with changes immediately visible to the GraphQL runner.

Frequently Asked Questions

Where is the GraphQL schema stored in Gatsby's architecture?

The compiled GraphQL schema object is stored in store.getState().schema, while the schema customization composer resides in store.getState().schemaCustomization.composer. This state is managed by the Redux store created in packages/gatsby/src/redux/index.ts and updated through dispatched actions during the build process.

How does the GraphQL runner access node data?

The GraphQLRunner class receives the Redux store as its first constructor argument in packages/gatsby/src/query/index.ts. During query execution, it accesses the node map directly via store.getState().nodes and the current schema via store.getState().schema. This design ensures queries always run against the most current data without requiring separate cache synchronization.

Can plugins modify the GraphQL schema during the build?

Yes. Plugins use the createTypes action available in gatsby-node.js APIs to dispatch Redux actions that update store.state.schema. The implementation in packages/gatsby/src/utils/create-schema-customization.ts processes these actions, allowing dynamic schema extensions that the GraphQL runner immediately recognizes in subsequent queries.

What happens to query results after execution?

After a query executes, the results are stored in the Redux state under state.graphqlState. This makes the data available to other plugins and internal APIs that need to consume GraphQL results during the build process, creating a reactive data flow where changes to the store propagate through the entire system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}