Handling stale nodes

Each time you run the gatsby build command, because Gatsby is fundamentally an SSG, there is always a nonzero chance that some node in the Redux nodes namespace will no longer be available because it’s been removed from the upstream data source. The Gatsby build lifecycle needs to be aware of this event in order to handle all nodes appropriately.

In addition to the Redux nodes namespace, there is a nodesTouched namespace that catalogues whether a particular node identifier has been touched by Gatsby during the node creation phase. This process occurs whenever nodes are created or when the touchNode function is called in the Gatsby API. Any nodes that haven’t been touched by the end of the node sourcing phase are deleted from the nodes namespace by identifying the delta between the nodesTouched and nodes Redux namespaces (as seen in src/utils/source-nodes.ts).

TIP

When a plugin using source-nodes runs again, it will re-create nodes (and therefore touch them). In certain scenarios, such as with some transformer plugins, a node may not actually change, though the node needs to be maintained for the build. For these cases, touchNode must be invoked explicitly by the plugin.

When you develop a Gatsby site, nodes are considered to be immutable unless those modifications are directly persisted to Gatsby’s Redux implementation through a Gatsby action. If you change a Node object directly without making Redux aware of the change, other areas of the Gatsby framework won’t be aware either. For this reason, always ensure that whenever you implement a Gatsby API such as onCreateNode you call a function such as createNodeField, which will add the updated field to the node’s node.fields object and persist the new state to Redux. This way, later logic in the plugin will execute properly based on this new state of the node in later build stages.

NOTE

For more information about build caching in Gatsby, for instance during the creation of nodes by source and transformer plugins, consult the guide to build caching in the Gatsby documentation.