Add a per-entry opt-out of copied filenames hashing

Author: pyrech

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## Unreleased
+
+- Add a per-entry `hash` option to `copy` (default `true`): when `false`, the copied file keeps its logical path on disk and the content hash moves to the `manifest.json` value as a query string, like Encore's `copyFiles()` allowed
+
 ## 0.7.0
 
 - Add the `RenderAssetTagEvent`, dispatched before each rendered `<script>`/`<link>` (including the injected dev client and React preamble), so listeners can add, change or remove attributes such as a CSP nonce

assets/src/core/copy.ts

@@ -7,8 +7,10 @@ import { joinUrl } from './format';
 export interface CopyResult {
     /** Path used for the manifest key, e.g. `images/icons/cat.svg`. */
     logicalName: string;
-    /** Path written under outputPath, hashed in build, verbatim in dev. */
+    /** Path written under outputPath: hashed in build (verbatim for `hash: false` entries and in dev). */
     physicalName: string;
+    /** `?<contenthash>` appended to the manifest value for `hash: false` entries in build, `''` otherwise. */
+    versionQuery: string;
     source: Buffer;
 }
 
@@ -25,8 +27,10 @@ function walk(dir: string, includeSubdirectories: boolean): string[] {
     return out;
 }
 
-export function enumerateCopyFiles(entries: ResolvedCopyEntry[]): Array<{ absPath: string; logicalName: string }> {
-    const out: Array<{ absPath: string; logicalName: string }> = [];
+export function enumerateCopyFiles(
+    entries: ResolvedCopyEntry[]
+): Array<{ absPath: string; logicalName: string; hash: boolean }> {
+    const out: Array<{ absPath: string; logicalName: string; hash: boolean }> = [];
     for (const entry of entries) {
         let files: string[];
         try {
@@ -38,7 +42,7 @@ export function enumerateCopyFiles(entries: ResolvedCopyEntry[]): Array<{ absPat
         for (const absPath of files) {
             const rel = relative(entry.from, absPath).split(sep).join('/');
             if (!entry.pattern.test(rel)) continue;
-            out.push({ absPath, logicalName: `${entry.to}/${rel}` });
+            out.push({ absPath, logicalName: entry.to ? `${entry.to}/${rel}` : rel, hash: entry.hash });
         }
     }
     return out;
@@ -54,11 +58,19 @@ export function hashedName(logicalName: string, hash: string): string {
     return `${base}.${hash}${ext}`;
 }
 
-export function resolveCopyFiles(entries: ResolvedCopyEntry[], hashed: boolean): CopyResult[] {
-    return enumerateCopyFiles(entries).map(({ absPath, logicalName }) => {
+export function resolveCopyFiles(entries: ResolvedCopyEntry[], build: boolean): CopyResult[] {
+    return enumerateCopyFiles(entries).map(({ absPath, logicalName, hash }) => {
         const source = readFileSync(absPath);
-        const physicalName = hashed ? hashedName(logicalName, contentHash(source)) : logicalName;
-        return { logicalName, physicalName, source };
+        if (!build) return { logicalName, physicalName: logicalName, versionQuery: '', source };
+        if (hash) {
+            return {
+                logicalName,
+                physicalName: hashedName(logicalName, contentHash(source)),
+                versionQuery: '',
+                source,
+            };
+        }
+        return { logicalName, physicalName: logicalName, versionQuery: `?${contentHash(source)}`, source };
     });
 }
 
@@ -68,7 +80,8 @@ export function copyManifest(
 ): Record<string, string> {
     const manifest: Record<string, string> = {};
     for (const file of files) {
-        manifest[opts.manifestKeyPrefix + file.logicalName] = joinUrl(opts.publicPath, file.physicalName);
+        manifest[opts.manifestKeyPrefix + file.logicalName] =
+            joinUrl(opts.publicPath, file.physicalName) + file.versionQuery;
     }
     return manifest;
 }

assets/src/core/options.ts

@@ -33,6 +33,7 @@ function normalizeCopy(copy: CopyEntry[] | undefined, cwd: string): ResolvedCopy
         to: normalizeCopyTo(entry.to),
         pattern: entry.pattern ?? /.*/,
         includeSubdirectories: entry.includeSubdirectories ?? true,
+        hash: entry.hash ?? true,
     }));
 }
 

assets/src/types.ts

@@ -139,19 +139,28 @@ export interface ResolvedStimulusOptions {
 export interface CopyEntry {
     /** Source directory, relative to the project root (cwd) or absolute. */
     from: string;
-    /** Logical destination prefix used for the manifest key (e.g. `images`). */
+    /** Logical destination prefix used for the manifest key (e.g. `images`); `''` copies at the root of `outputPath`. */
     to: string;
     /** Only files whose path relative to `from` matches this regex are copied. Default: every file. */
     pattern?: RegExp;
     /** Recurse into subdirectories of `from`. Default: true. */
     includeSubdirectories?: boolean;
+    /**
+     * Content-hash the emitted filename. Default: true.
+     *
+     * When false, the file keeps its logical path on disk and the content hash
+     * moves to the manifest value as a query string (Encore's `copyFiles()`
+     * contract) — for files referenced by a stable path outside the manifest.
+     */
+    hash?: boolean;
 }
 
 export interface ResolvedCopyEntry {
     from: string;
     to: string;
     pattern: RegExp;
     includeSubdirectories: boolean;
+    hash: boolean;
 }
 
 /** Map of Stimulus identifier -> controller class (registered eagerly). */

assets/test/core/copy.test.ts

@@ -7,7 +7,7 @@ const src = join(import.meta.dirname, '../fixtures/copy-src');
 const binSrc = join(import.meta.dirname, '../fixtures/copy-binary');
 
 function entry(over: Partial<ResolvedCopyEntry> = {}): ResolvedCopyEntry {
-    return { from: src, to: 'images', pattern: /.*/, includeSubdirectories: true, ...over };
+    return { from: src, to: 'images', pattern: /.*/, includeSubdirectories: true, hash: true, ...over };
 }
 
 describe('enumerateCopyFiles', () => {
@@ -36,10 +36,17 @@ describe('enumerateCopyFiles', () => {
         expect(enumerateCopyFiles([entry({ from: join(src, 'does-not-exist') })])).toEqual([]);
     });
 
+    it('copies at the root of outputPath when `to` is empty', () => {
+        const names = enumerateCopyFiles([entry({ to: '', pattern: /\.txt$/ })])
+            .map((f) => f.logicalName)
+            .sort();
+        expect(names).toEqual(['notes.txt']);
+    });
+
     it('aggregates multiple entries under their own `to` prefixes', () => {
         const names = enumerateCopyFiles([
             entry({ to: 'a', pattern: /\.svg$/ }),
-            { from: binSrc, to: 'b', pattern: /.*/, includeSubdirectories: true },
+            { from: binSrc, to: 'b', pattern: /.*/, includeSubdirectories: true, hash: true },
         ])
             .map((f) => f.logicalName)
             .sort();
@@ -67,6 +74,21 @@ describe('resolveCopyFiles', () => {
     it('uses verbatim physical names when hashed=false', () => {
         const logo = resolveCopyFiles([entry()], false).find((f) => f.logicalName === 'images/logo.svg')!;
         expect(logo.physicalName).toBe('images/logo.svg');
+        expect(logo.versionQuery).toBe('');
+    });
+
+    it('keeps the logical path and moves the hash to versionQuery for `hash: false` entries in build', () => {
+        const logo = resolveCopyFiles([entry({ hash: false })], true).find((f) => f.logicalName === 'images/logo.svg')!;
+        expect(logo.physicalName).toBe('images/logo.svg');
+        expect(logo.versionQuery).toMatch(/^\?[0-9a-f]{8}$/);
+    });
+
+    it('does not version `hash: false` entries in dev', () => {
+        const logo = resolveCopyFiles([entry({ hash: false })], false).find(
+            (f) => f.logicalName === 'images/logo.svg'
+        )!;
+        expect(logo.physicalName).toBe('images/logo.svg');
+        expect(logo.versionQuery).toBe('');
     });
 });
 
@@ -77,6 +99,12 @@ describe('copyManifest', () => {
         expect(manifest['build/images/logo.svg']).toMatch(/^\/build\/images\/logo\.[0-9a-f]{8}\.svg$/);
         expect(manifest['build/images/icons/cat.svg']).toMatch(/^\/build\/images\/icons\/cat\.[0-9a-f]{8}\.svg$/);
     });
+
+    it('appends the version query for `hash: false` entries', () => {
+        const files = resolveCopyFiles([entry({ hash: false })], true);
+        const manifest = copyManifest(files, { publicPath: '/build/', manifestKeyPrefix: 'build/' });
+        expect(manifest['build/images/logo.svg']).toMatch(/^\/build\/images\/logo\.svg\?[0-9a-f]{8}$/);
+    });
 });
 
 describe('contentHash', () => {

assets/test/core/options.test.ts

@@ -115,7 +115,13 @@ describe('normalizeOptions', () => {
     it('resolves a relative copy `from` against cwd and applies defaults', () => {
         const r = normalizeOptions({ copy: [{ from: 'assets/images', to: 'images' }] }, '/app');
         expect(r.copy).toEqual([
-            { from: join('/app', 'assets/images'), to: 'images', pattern: /.*/, includeSubdirectories: true },
+            {
+                from: join('/app', 'assets/images'),
+                to: 'images',
+                pattern: /.*/,
+                includeSubdirectories: true,
+                hash: true,
+            },
         ]);
     });
 
@@ -130,6 +136,11 @@ describe('normalizeOptions', () => {
         expect(r.copy[0].includeSubdirectories).toBe(false);
     });
 
+    it('honors `hash: false` on a copy entry', () => {
+        const r = normalizeOptions({ copy: [{ from: '/src/img', to: 'images', hash: false }] }, '/app');
+        expect(r.copy[0].hash).toBe(false);
+    });
+
     it('normalizes a `to` with a leading "./" and trailing slash to a clean prefix', () => {
         // A leading "./" would leak into the manifest key ("build/./to-copy/…") and, in Vite,
         // Rollup rejects an emitted fileName that looks like a relative path ("./to-copy/…").

assets/test/integration/copy.test.ts

@@ -31,6 +31,26 @@ describe('vite copy', () => {
         expect(existsSync(join(out, physical))).toBe(true);
     }, 30_000);
 
+    it('build: `hash: false` entries keep their logical path, versioned in the manifest query', async () => {
+        const out = mkdtempSync(join(tmpdir(), 'ups-copy-vite-nohash-'));
+        await build({
+            root: fixture,
+            logLevel: 'silent',
+            build: { emptyOutDir: true, rollupOptions: { input: { app: join(fixture, 'app.js') } } },
+            plugins: [
+                SymfonyVite({
+                    outputPath: out,
+                    publicPath: '/build/',
+                    copy: [{ from: copySrc, to: 'images', hash: false }],
+                }),
+            ],
+        });
+
+        const manifest = JSON.parse(readFileSync(join(out, 'manifest.json'), 'utf8'));
+        expect(manifest['build/images/logo.svg']).toMatch(/^\/build\/images\/logo\.svg\?[0-9a-f]{8}$/);
+        expect(existsSync(join(out, 'images/logo.svg'))).toBe(true);
+    }, 30_000);
+
     it('build: no copy option leaves the manifest without image keys', async () => {
         const out = mkdtempSync(join(tmpdir(), 'ups-copy-vite-off-'));
         await build({
@@ -143,6 +163,26 @@ describe('rsbuild copy', () => {
         expect(existsSync(join(out, physical))).toBe(true);
     }, 60_000);
 
+    it('build: `hash: false` entries keep their logical path, versioned in the manifest query', async () => {
+        const out = mkdtempSync(join(tmpdir(), 'ups-copy-vite-nohash-'));
+        await build({
+            root: fixture,
+            logLevel: 'silent',
+            build: { emptyOutDir: true, rollupOptions: { input: { app: join(fixture, 'app.js') } } },
+            plugins: [
+                SymfonyVite({
+                    outputPath: out,
+                    publicPath: '/build/',
+                    copy: [{ from: copySrc, to: 'images', hash: false }],
+                }),
+            ],
+        });
+
+        const manifest = JSON.parse(readFileSync(join(out, 'manifest.json'), 'utf8'));
+        expect(manifest['build/images/logo.svg']).toMatch(/^\/build\/images\/logo\.svg\?[0-9a-f]{8}$/);
+        expect(existsSync(join(out, 'images/logo.svg'))).toBe(true);
+    }, 30_000);
+
     it('build: no copy option leaves the manifest without image keys', async () => {
         const out = mkdtempSync(join(tmpdir(), 'ups-copy-rsbuild-off-'));
         const rsbuild = await createRsbuild({

doc/index.rst

@@ -328,6 +328,28 @@ the destination prefix used for the manifest key. Restrict which files are copie
 expression tested against each file's path relative to ``from`` (by default every file is copied).
 ``includeSubdirectories`` defaults to ``true``; set it to ``false`` to turn off recursion.
 
+Some copied files must keep a stable path on disk: templates referencing them by a hardcoded
+``asset('/build/images/logo.svg')``, code reading them from a predictable location, CDN rules… Set ``hash: false``
+on the entry to keep the logical path verbatim; the content hash then moves to the ``manifest.json`` value as a
+query string, so cache-busting through ``asset()`` keeps working:
+
+.. code-block:: javascript
+
+    copy: [
+      {
+        from: 'assets/images',
+        to: 'images',
+        hash: false,
+      },
+    ],
+
+.. code-block:: json
+
+    { "build/images/logo.svg": "/build/images/logo.svg?87dcc351" }
+
+Note that proxies or CDNs configured to ignore query strings will not pick up new versions of these files — which
+is why hashed filenames remain the default.
+
 How copied files are handled depends on the mode:
 
 - **Build**: each file gets a content hash in its filename for cache busting.