Are Rollup content hashes a safe caching contract across major upgrades?

Question

We use Rollup's output.entryFileNames and chunkFileNames with [hash] placeholders so browsers and our CDN can cache emitted chunks long-term. This works well within a single Rollup version, but we are unsure what guarantees exist when we upgrade.The documentation describes how hashes are generated from chunk content, but I cannot find a clear statement about whether the hashing algorithm, chunk-splitting heuristics, or default output formats are stable across major versions (for example 3.x to 4.x). If an identical source tree produces different chunk boundaries or different hashes after an upgrade, every cached URL changes at once, which effectively invalidates our long-term caching strategy and complicates comparing pre- and post-upgrade builds.We pin the exact Rollup version and commit our lockfile, so rollback itself is not the concern; the concern is knowing which parts of the emitted output we can treat as a contract.Is chunk content hashing documented as stable across major versions, or explicitly not guaranteed? Are chunk-splitting decisions part of any stability guarantee, or only the plugin hook API? What do teams relying on long-term caching typically diff (file names, hashes, warnings) to verify an upgrade is output-equivalent before shipping it?

Tasadduq Burney · Answer

Short answer
No. Rollup does not publish a formal guarantee that the hash value embedded in output.entryFileNames or output.chunkFileNames will stay identical when you upgrade between major releases. The hashing algorithm, chunk‑splitting heuristics, and even default output format are all internal implementation details that have changed between 3.x and 4.x, and they are not version‑pinned in the public API.
Why the contract is fragile

Hash algorithm changes: 3.x used a SHA‑1‑based hash, 4.x switched to SHA‑256. The hash is computed over the emitted module content plus a few metadata fields.
Chunk‑splitting heuristics evolve: Automatic splitting, manual chunks, and dynamic imports are governed by internal heuristics that have been tweaked across releases, so identical source trees can end up in different chunk boundaries.
Output defaults shift: The default output.format and source‑map handling affect the hash calculation. A change in defaults can alter the hash even if the code itself is unchanged.

What is documented
Rollup’s documentation explains that [hash] is derived from the chunk content, but it does not state that the algorithm or the set of data used to compute it is stable across major releases. The only part that is stable is the hash placeholder itself, not the underlying value.
Practical guidance for teams that rely on long‑term caching

Pin the Rollup version in package.json and lock the dependency graph with npm ci or yarn install --frozen-lockfile.
Build twice – once with the current Rollup and once with the target major upgrade – into separate output directories (e.g., dist-v3 and dist-v4).
Diff the outputs:
diff -rq dist-v3 dist-v4
# or use a tool that compares file names and hash parts only

Inspect any differences:

Different hash values in the same file name? Likely a changed hashing algorithm or altered metadata.
New or missing file names? Indicates a change in chunk‑splitting heuristics or plugin behavior.

Decide on a strategy:

If the hashes are identical and the file set is unchanged, you can safely keep the CDN cache.
If any differences exist, you must purge the affected URLs or adjust the cache‑busting policy before shipping the upgrade.

Typical verification checklist

CheckTool / CommandWhat to look for

File namesgrep or lsSame set of names, same hash segment
Hash segmentawk/sed to extract the hash partExact match or explain why it differs
Content equalitysha256sum of filesSame content if hash differs
Plugin side‑effectsCheck plugin docs for changes in output formatEnsure no new metadata added that changes hash

What to ask when you need a more tailored recommendation
To fine‑tune the approach, we’d need to know the target Rollup version you plan to upgrade to. Different major releases may introduce different changes that affect the hash calculation.
Bottom line
Assume the hash contract is not guaranteed across major Rollup upgrades. Treat it as an implementation detail and validate the output after each upgrade before relying on CDN cache keys.

Are Rollup content hashes a safe caching contract across major upgrades?

1 answer

Short answer

Why the contract is fragile

What is documented

Practical guidance for teams that rely on long‑term caching

Typical verification checklist

What to ask when you need a more tailored recommendation

Bottom line

Your perspective belongs here.

0 question comments

Check	Tool / Command	What to look for
File names	grep or `ls`	Same set of names, same hash segment
Hash segment	awk/sed to extract the hash part	Exact match or explain why it differs
Content equality	sha256sum of files	Same content if hash differs
Plugin side‑effects	Check plugin docs for changes in output format	Ensure no new metadata added that changes hash