Ensuring deterministic build outputs in Qwik v1.5

Enforcing Build Reproducibility

To ensure deterministic build outputs in Qwik v1.5, you must configure the underlying Vite/Rollup pipeline for determinism and stabilize the environment's filesystem interactions. There is currently no dedicated "seed" configuration for the Qwik Optimizer's symbol mangling; instead, the optimizer relies on a stable module graph provided by Rollup.

Required Configuration

Enable the deterministic flag in your Vite configuration. This forces Rollup to use consistent chunk IDs and strip timestamps, which prevents hashes from changing across different CI agents when the source code remains identical.

// vite.config.ts or qwik.config.ts
export default {
  build: {
    deterministic: true,
    minify: 'esbuild',
  },
};

Addressing Non-Deterministic Factors

While the build pipeline is largely deterministic, two primary areas can introduce variance:

• Route Generation: Qwik City scans the src/routes directory using fs.readdir. Because directory listing order is OS-dependent (e.g., Linux vs. Windows), the route manifest order may vary. To mitigate this, ensure your build environment uses a consistent locale (e.g., LC_ALL=C) or use a Docker container to standardize the filesystem behavior.
• Module Resolution: Non-determinism in symbol mangling is typically a symptom of an unstable module graph rather than the mangler itself. Ensuring build.deterministic: true is set and using a locked package manager (pnpm, npm, or yarn) with a committed lockfile is the primary defense.

Verification Steps

To verify that your builds are reproducible across different environments, use the following scoped approach:

1. Local Hash Comparison: Run the build twice on one machine and compare the checksums of the output files:

   sha256sum dist/**/* | sort > build1.txt
       # Run build again
       sha256sum dist/**/* | sort > build2.txt
       diff build1.txt build2.txt

2. Cross-OS Validation: Run the build in a clean node:20-alpine Docker container and compare the resulting dist/client/entry.manifest.json with a build from a different OS. The chunks ordering and id values should be identical.

Diagnostic Requirement

If you are still seeing divergent hashes after applying these settings, please provide the Node.js version and OS used across your CI agents, as differences in glibc or Node's internal filesystem handling can occasionally impact the Qwik City route scanning order.