Gatsby Core and React: Interoperability during Major Version Upgrades

Integration Boundary Constraints

Upgrading Gatsby to a new major version often necessitates a corresponding update to the React peer dependency. Because Gatsby's internal rendering logic and the gatsby-plugin-image ecosystem rely on specific React version ranges, a mismatch between the core framework and the component library can lead to runtime errors or hydration mismatches.

Cache and State Persistence

During the transition, the .cache and public directories contain artifacts generated by the previous version's GraphQL schema and build logic. While clearing these directories is a standard recovery step, there is no standardized policy within the core framework regarding the preservation of these artifacts for debugging purposes versus automatic purging in CI/CD pipelines to ensure a clean state.

Given these constraints, what is the recommended strategy for managing the React peer dependency boundary to avoid runtime conflicts? Additionally, should the build cache be preserved or purged automatically when a version upgrade fails in a headless environment?