# Understanding the Gatsby Redux Store and GraphQL Data Layer Relationship

> Explore the Gatsby Redux store and its deep connection to the GraphQL data layer Learn how Redux acts as the central hub for your build process, managing schema, node data, and query state for efficient data retrieval.

- Repository: [Gatsby/gatsby](https://github.com/gatsbyjs/gatsby)
- Tags: deep-dive
- Published: 2026-03-06

---

**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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/query/index.ts), the runner is instantiated lazily:

```typescript
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`](https://github.com/gatsbyjs/gatsby/blob/main/gatsby-node.js), it triggers an action that updates `store.state.schema`:

```javascript
// 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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/gatsby-node.js) APIs to dispatch Redux actions that update `store.state.schema`. The implementation in [`packages/gatsby/src/utils/create-schema-customization.ts`](https://github.com/gatsbyjs/gatsby/blob/main/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.