Gatsby v5's Node.js 18 requirement blocks CI upgrades for legacy projects

Answer the Exact Question First

1. Pin Gatsby to v4 or upgrade Node? If the rest of the monorepo can stay on Node 14/16, pin gatsby to the last v4 release to keep the current CI image working. If a coordinated runtime upgrade is feasible, move the whole repo to Node 18+ – this is the long‑term path because Node 14/16 are EOL and Gatsby v5 plugins increasingly rely on newer APIs.

2. Re‑key CI caching when engines checks are bypassed? Never rely on --ignore-engines for a production build. Instead, include the Node and Gatsby versions in the cache key (e.g., node-${{ matrix.node-version }}-gatsby-${{ matrix.gatsby-version }}) so a mismatch forces a fresh install.

3. Handling native module rebuilds (sharp) during the transition? Run a clean install in a Node 18 container and rebuild sharp from source. Clear the node_modules/.cache directory before each major Node upgrade to avoid ABI mismatches.

Why Pin to Gatsby v4?

Gatsby v4 declares engines: { node: ">=12" }, so it installs fine on Node 14/16. This keeps the existing CI image (node:14 or ubuntu-latest) functional. The trade‑off is missing v5 performance improvements and the latest security patches for Gatsby core.

Why Upgrade to Node 18+?

Node 14 reached EOL in April 2023 and Node 16 in April 2024. Many Gatsby v5 plugins now import fs/promises or use worker_threads, which are stable only from Node 12+ but are more fully supported in Node 18+. A coordinated upgrade also aligns all services to a single runtime, reducing tool‑chain complexity.

Re‑configuring CI Caching

1. Define a cache key that reflects both the Node and Gatsby versions. Example for GitHub Actions:

   steps:
     - uses: actions/cache@v3
       with:
         path: ~/.npm
         key: ${{ runner.os }}-node-${{ matrix.node-version }}-gatsby-${{ matrix.gatsby-version }}
   

2. Do not use --ignore-engines unless you have a verified runtime that matches the engines field. If you must, add a pre‑install script that checks process.version against the required Node range and aborts on mismatch.

Rebuilding Native Modules (sharp)

1. Spin up a fresh Node 18 container: docker run --rm -v $(pwd):/app node:18 bash.
2. Inside the container, run:

   npm ci
   npm rebuild sharp --build-from-source
   

3. Commit the rebuilt node_modules/.cache or exclude it from the cache; always rebuild sharp when the Node major version changes.
4. Add a lightweight test that imports sharp and logs its version to catch ABI mismatches early.

Verification Steps (for the reader)

• Check the engines field in the installed Gatsby package: cat node_modules/gatsby/package.json | grep engines.
• Run a dry install in a legacy image to see the EBADENGINE error: docker run --rm -v $(pwd):/app node:14 npm install gatsby.
• Build with Node 18 and the cache cleared to confirm sharp rebuild succeeds.

Missing Diagnostic Detail

To tailor the recommendation precisely, please confirm the Node versions currently used across the monorepo’s services. If all services share the same Node version, a coordinated upgrade is simpler; if they differ, consider per‑service tooling (nvm, volta, or Docker multi‑stage) to isolate runtimes.