Version static asset URLs by a fingerprint of the files, so browsers fetch new scripts after each deploy

This commit is contained in:
zyphlar
2026-11-07 23:26:45 -08:00
parent 1db425d493
commit f08207516d
2 changed files with 77 additions and 4 deletions
+35 -4
View File
@@ -1,7 +1,38 @@
import { join } from 'path'
import { resolveAppVersion } from '@ipp/core'
import { createHash } from 'crypto'
import { readdirSync, readFileSync } from 'fs'
import { join, relative } from 'path'
import { CORE_PUBLIC_DIR, resolveAppVersion } from '@ipp/core'
export const APP_VERSION = resolveAppVersion(join(__dirname, '..', 'package.json'))
/** URL-safe cache-busting segment for static asset paths. */
export const ASSET_VERSION = encodeURIComponent(APP_VERSION)
/**
* A short fingerprint of every static file served under the versioned path.
* Browsers cache those files for a long time without checking back, so the
* path has to change whenever any of them does. The package version alone
* doesn't: it stays the same across builds of one release.
*/
export function staticFingerprint (dirs: string[]): string {
const hash = createHash('sha256')
for (const dir of dirs) {
let entries: string[]
try {
entries = readdirSync(dir, { recursive: true, encoding: 'utf8' })
} catch {
continue // a missing folder simply contributes nothing
}
for (const entry of entries.sort()) {
const path = join(dir, entry)
let content: Buffer
try {
content = readFileSync(path)
} catch {
continue // a directory
}
hash.update(relative(dir, path)).update('\0').update(content).update('\0')
}
}
return hash.digest('hex').slice(0, 10)
}
/** URL-safe cache-busting segment for static asset paths: the version plus the files' fingerprint. */
export const ASSET_VERSION = encodeURIComponent(APP_VERSION + '-' + staticFingerprint([join(__dirname, '..', 'public'), CORE_PUBLIC_DIR]))
+42
View File
@@ -0,0 +1,42 @@
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'fs'
import { tmpdir } from 'os'
import { join } from 'path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { ASSET_VERSION, staticFingerprint } from '../src/version'
let dir: string
beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), 'imp-assets-'))
mkdirSync(join(dir, 'js'))
writeFileSync(join(dir, 'js', 'app.js'), 'one')
writeFileSync(join(dir, 'style.css'), 'body {}')
})
afterEach(() => rmSync(dir, { recursive: true, force: true }))
describe('static asset version', () => {
it('stays the same while the files do', () => {
expect(staticFingerprint([dir])).toBe(staticFingerprint([dir]))
expect(staticFingerprint([dir])).toMatch(/^[0-9a-f]{10}$/)
})
it('changes when a file changes, is added, or is renamed', () => {
const before = staticFingerprint([dir])
writeFileSync(join(dir, 'js', 'app.js'), 'two')
const edited = staticFingerprint([dir])
expect(edited).not.toBe(before)
writeFileSync(join(dir, 'js', 'new.js'), '')
const added = staticFingerprint([dir])
expect(added).not.toBe(edited)
rmSync(join(dir, 'js', 'new.js'))
writeFileSync(join(dir, 'js', 'renamed.js'), '')
expect(staticFingerprint([dir])).not.toBe(added)
})
it('ignores a missing folder', () => {
expect(staticFingerprint([dir, join(dir, 'nope')])).toBe(staticFingerprint([dir]))
})
it('puts the fingerprint after the package version in the asset path', () => {
expect(decodeURIComponent(ASSET_VERSION)).toMatch(/^.+-[0-9a-f]{10}$/)
})
})