Page -> Node Dependency Tracking

This documentation isn’t up to date with the latest schema customization changes.

Outdated areas are:

• createPageDependency is not the only way to mutate dependencies now
• other helpers exist now

You can help by making a PR to update this documentation.

In almost every GraphQL Resolver, you’ll see the createPageDependency, or getNodeAndSavePathDependency functions. These are responsible for recording which nodes are depended on by which pages. In develop mode, when a node’s content is changed the pages whose queries depend on that node will be re-run. This is one of the things that makes develop so awesome.

How dependencies are recorded

Recording of Page -> Node dependencies are handled by the createPageDependency action. It takes the page (in the form of its path), and either a nodeId, or connection.

Passing nodeId tells Gatsby that the page depends specifically on this node. So, if the node is changed, then the page’s query needs to be re-executed.

connection is a Type string. E.g. MarkdownRemark, or File. Calling createPageDependency with a page path and a connection tells Gatsby that this page depends on all nodes of this type. Therefore if any node of this type changes (e.g. a change to a markdown node), then this page must be rebuilt. This variant is only called from run-sift.js when a query such as allFile, or allMarkdownRemark is run. See Schema Connections for more info.

How dependencies are stored

Page -> Node dependencies are tracked via the componentDataDependencies redux namespace. createPageDependency is the only way to mutate it. The namespace is comprised of two sub structures:

Nodes is a map of nodeID to the set of pages that depend on that node. E.g

Connections is a map of type name to the set of pages that depend on that type. e.g

How dependency information is used

Page -> Node dependencies are used entirely during query execution to figure out which nodes are “dirty”, and therefore which page’s queries need to be re-executed. This occurs in page-query-runner.js in the findIdsWithoutDataDependencies and findDirtyIds functions. This is described in greater detail in the Query Execution docs.

Other forms

add-page-dependency.js

redux/actions/add-page-dependency.js is a wrapper around the createPageDependency action that performs some additional performance optimizations. It should be used instead of the raw action.

getNodeAndSavePathDependency action

The getNodeAndSavePathDependency action simply calls getNode, and then calls createPageDependency using that result. It is a programmer convenience.