Repeatable Gatsby dev environment with Node pinning and lockfiles

Nondeterministic Build Artifacts

Even with a pinned Node version (via .nvmrc or engines) and a committed lockfile, several build artifacts remain nondeterministic across different machines. The primary sources of divergence are environment-specific metadata and platform-dependent binary processing.

Non-Reproducible Outputs

• Image Derivatives: Assets processed by gatsby-plugin-sharp are not bit-for-bit identical across operating systems. This is due to variations in libvips floating-point behavior, CPU instruction sets (SIMD), and OS-specific color profile handling.
• The public/ Directory: While the logical content is the same, the physical files differ. HTML files often contain build timestamps, and JSON payloads may embed file-system modification times (mtimes) via gatsby-source-filesystem.
• Chunk Hashes: Webpack chunk filenames are based on content hashes. If the underlying .cache state or environment metadata differs, the resulting hashes for JS and CSS bundles can shift.
• GraphQL Schema: The schema is generally deterministic, but divergence occurs if source plugins rely on OS-specific readdir ordering or file-system stats (like inode hashes or birthtimes).

Incremental Cache and Divergence Risk

The .cache directory is designed to be machine-specific and should not be shared. Because it stores local file-system metadata and absolute paths, attempting to sync it across machines often leads to build failures or corrupted state.

Does lack of a shared cache create divergence? No, not in terms of functional output. When .cache is absent, Gatsby performs a full rebuild. While this loses the speed of incremental builds and changes the resulting artifact hashes, it does not change the final rendered page content. The risk is not functional divergence, but a lack of binary reproducibility.

Verification Steps

To verify the level of divergence in your specific environment, run the following on two different machines (e.g., macOS and Linux) using the same commit:

# Ensure a clean state and strict dependency install
gatsby clean
npm ci
gatsby build

Compare the public/ folders. You will likely find that while the HTML structure is identical, the image binaries and hashed filenames differ.

Diagnostic Requirement

Are you using any custom source plugins that fetch data from local system environment variables or OS-level APIs? If so, these must be externalized to a .env file to maintain consistency.