build-toolchain

Compare the runtime versions (.nvmrc vs CI image), install modes (CI must use frozen installs like npm ci), filesystem case sensitivity, and environment variables. Linux CI on case-sensitive filesystems catches path casing errors that macOS misses.

Common causes include Date.now() baked into output, unsorted filesystem glob results, parallel emitter races misaligning source maps, and network-fetching postinstall scripts. Pin runtimes, lockfiles, and sort glob results before consumption.

Use pnpm or yarn with workspaces for Node monorepos, and pick exactly one per repo. pnpm symlinks instead of flattening node_modules, so code assuming a flat layout breaks; test on the chosen layout and pin the package manager version.

Tree shaking drops side-effectful imports unless they are declared in the package.json sideEffects field. It also requires ESM sources and breaks silently on re-export barrels and namespace property access.

Only fast, localized, idempotent checks like formatting, linting staged files, and secret scans. Exclude test suites, build steps, network calls, and hooks that touch unstaged files; pin every hook to a tagged release.

Grep the built output for import specifiers and confirm only expected dependencies like react appear. Anything extra means a dependency got inlined; anything missing means it was incorrectly bundled into the artifact.