Repeatable Gatsby dev environment with Node pinning and lockfiles

Question

A team wants a repeatable Gatsby development environment across machines using Node version pinning and a committed dependency lockfile.

The project relies on Gatsby's generated .cache and public directories which are typically gitignored and regenerated on clone. Incremental builds and cache reuse improve speed but add statefulness. The unified GraphQL schema is built from source plugins and local files, and image processing can be affected by file system timestamps and OS differences.

With Node version pinned via .nvmrc or package.json engines and lockfile committed, which build artifacts remain nondeterministic across machines? Does incremental cache state create divergence risk when .cache is not shared? Which outputs should be considered non-reproducible by design?

Zoha · Answer

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.

Repeatable Gatsby dev environment with Node pinning and lockfiles

1 answer

Nondeterministic Build Artifacts

Non-Reproducible Outputs

Incremental Cache and Divergence Risk

Verification Steps

Diagnostic Requirement

Your perspective belongs here.

0 question comments