Page -> Node Dependency Tracking
This documentation isn’t up to date with the latest schema customization changes.
Outdated areas are:
createPageDependencyis 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.
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 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.
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
allMarkdownRemark is run. See Schema Connections for more info.
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
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.
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.
The getNodeAndSavePathDependency action simply calls
getNode, and then calls
createPageDependency using that result. It is a programmer convenience.