feature #16 [Copy] Copy static files into the build and register them in the manifest (Kocal)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Copy] Copy static files into the build and register them in the manifest

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | Fix #... <!-- prefix each issue number with "Fix #", no need to open an issue if none exists, explain below instead -->
| License       | MIT

Add a `copy` option that copies static files (images, fonts) referenced by
a stable path from Twig into the build output and records them in
manifest.json, so the asset() helper resolves them to their URL. Names are
content-hashed in build mode and verbatim in dev; files are written under
outputPath (public/build) and served by the Symfony web server, so they are
available whether or not the dev server is running.

Implemented for both Vite and Rsbuild on a shared, bundler-agnostic core.

Commits
-------

b8e4809 [Copy] Copy static files into the build and register them in the manifest

Author: Kocal

README.md

@@ -28,6 +28,7 @@ Symfony Reprise covers only the Symfony-side glue the bundlers leave out:
 - 📄 **`entrypoints.json`**: generated in both build and dev-server modes
 - 🗺️ **`manifest.json`**: maps each logical filename to its hashed URL
 - 🔖 **Asset versioning**: content-hash cache busting, wired into the manifest
+- 📁 **File copy**: copy static files (images, fonts…) into the build, keyed in the manifest
 - 🔥 **Dev server & HMR**: points Twig at the running Vite/Rsbuild server
 - 🧩 **Symfony UX / Stimulus**: registers `controllers.json` and local controllers, eager or lazy
 - 🌐 **CDN support**: serve built assets from an absolute `publicPath`

assets/src/core/copy.ts

@@ -0,0 +1,82 @@
+import type { ResolvedCopyEntry } from '../types';
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, sep } from 'node:path';
+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. */
+    physicalName: string;
+    source: Buffer;
+}
+
+function walk(dir: string, includeSubdirectories: boolean): string[] {
+    const out: string[] = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const abs = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (includeSubdirectories) out.push(...walk(abs, includeSubdirectories));
+        } else {
+            out.push(abs);
+        }
+    }
+    return out;
+}
+
+export function enumerateCopyFiles(entries: ResolvedCopyEntry[]): Array<{ absPath: string; logicalName: string }> {
+    const out: Array<{ absPath: string; logicalName: string }> = [];
+    for (const entry of entries) {
+        let files: string[];
+        try {
+            files = walk(entry.from, entry.includeSubdirectories);
+        } catch {
+            console.warn(`[@symfony/reprise] copy: source directory "${entry.from}" not found, skipping`);
+            continue;
+        }
+        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}` });
+        }
+    }
+    return out;
+}
+
+export function contentHash(source: Buffer): string {
+    return createHash('sha256').update(source).digest('hex').slice(0, 8);
+}
+
+export function hashedName(logicalName: string, hash: string): string {
+    const ext = extname(logicalName);
+    const base = ext ? logicalName.slice(0, -ext.length) : logicalName;
+    return `${base}.${hash}${ext}`;
+}
+
+export function resolveCopyFiles(entries: ResolvedCopyEntry[], hashed: boolean): CopyResult[] {
+    return enumerateCopyFiles(entries).map(({ absPath, logicalName }) => {
+        const source = readFileSync(absPath);
+        const physicalName = hashed ? hashedName(logicalName, contentHash(source)) : logicalName;
+        return { logicalName, physicalName, source };
+    });
+}
+
+export function copyManifest(
+    files: CopyResult[],
+    opts: { publicPath: string; manifestKeyPrefix: string }
+): Record<string, string> {
+    const manifest: Record<string, string> = {};
+    for (const file of files) {
+        manifest[opts.manifestKeyPrefix + file.logicalName] = joinUrl(opts.publicPath, file.physicalName);
+    }
+    return manifest;
+}
+
+export function writeCopyFiles(files: CopyResult[], outputPath: string): void {
+    for (const file of files) {
+        const dest = join(outputPath, file.physicalName);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, file.source);
+    }
+}

assets/src/core/format.ts

@@ -1,6 +1,6 @@
 import type { BuildContext, EntryFiles, EntrypointsJson, ManifestJson, NormalizedGraph } from '../types';
 
-function joinUrl(prefix: string, name: string): string {
+export function joinUrl(prefix: string, name: string): string {
     return prefix.endsWith('/') ? prefix + name : `${prefix}/${name}`;
 }
 

assets/src/core/options.ts

@@ -1,11 +1,32 @@
-import type { Options, ResolvedOptions, ResolvedStimulusOptions } from '../types';
+import type { CopyEntry, Options, ResolvedCopyEntry, ResolvedOptions, ResolvedStimulusOptions } from '../types';
 import * as path from 'node:path';
 
 function normalizeIntegrity(integrity: Options['integrity']): ResolvedOptions['integrity'] {
     if (!integrity?.enabled) return undefined;
     return { algorithms: integrity.algorithms?.length ? [...integrity.algorithms] : ['sha384'] };
 }
 
+function normalizeCopyTo(to: string): string {
+    // Collapse "." segments and redundant slashes, then drop any leading "./" or "/" and trailing
+    // "/". A leading "./" or "/" would corrupt the manifest key ("build/./to-copy/…") and, in the
+    // Vite path, make Rollup reject the emitted asset fileName (it forbids relative-looking paths).
+    const normalized = path.posix.normalize(to.replace(/\\/g, '/'));
+    return normalized
+        .replace(/^\.?\/+/, '')
+        .replace(/^\.$/, '')
+        .replace(/\/+$/, '');
+}
+
+function normalizeCopy(copy: CopyEntry[] | undefined, cwd: string): ResolvedCopyEntry[] {
+    if (!copy) return [];
+    return copy.map((entry) => ({
+        from: path.isAbsolute(entry.from) ? entry.from : path.join(cwd, entry.from),
+        to: normalizeCopyTo(entry.to),
+        pattern: entry.pattern ?? /.*/,
+        includeSubdirectories: entry.includeSubdirectories ?? true,
+    }));
+}
+
 function normalizeStimulus(stimulus: Options['stimulus'], cwd: string): ResolvedStimulusOptions | undefined {
     if (!stimulus) return undefined;
     const raw = typeof stimulus === 'string' ? { controllersJson: stimulus } : stimulus;
@@ -44,6 +65,7 @@ export function normalizeOptions(options: Options | undefined, cwd: string): Res
         devServerOrigin: options?.devServerOrigin,
         stimulus: normalizeStimulus(options?.stimulus, cwd),
         integrity: normalizeIntegrity(options?.integrity),
+        copy: normalizeCopy(options?.copy, cwd),
     };
 }
 

assets/src/index.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import * as process from 'node:process';
 import { createUnplugin } from 'unplugin';
 import { bundleToGraph, configToDevGraph } from './collectors/vite';
+import { copyManifest, resolveCopyFiles, writeCopyFiles } from './core/copy';
 import { resolveDevOrigin } from './core/dev-server';
 import { writeSymfonyFiles } from './core/emit';
 import { buildEntrypoints, buildManifest } from './core/format';
@@ -49,10 +50,21 @@ export const unpluginFactory: UnpluginFactory<Options | undefined> = (options, _
                     fileName: 'entrypoints.json',
                     source: `${JSON.stringify(buildEntrypoints(graph, ctx), null, 2)}\n`,
                 });
+                const copyFiles = resolveCopyFiles(resolved.copy, true);
+                for (const file of copyFiles) {
+                    this.emitFile({ type: 'asset', fileName: file.physicalName, source: file.source });
+                }
+                const manifest = {
+                    ...buildManifest(graph, ctx),
+                    ...copyManifest(copyFiles, {
+                        publicPath: resolved.publicPath,
+                        manifestKeyPrefix: resolved.manifestKeyPrefix,
+                    }),
+                };
                 this.emitFile({
                     type: 'asset',
                     fileName: 'manifest.json',
-                    source: `${JSON.stringify(buildManifest(graph, ctx), null, 2)}\n`,
+                    source: `${JSON.stringify(manifest, null, 2)}\n`,
                 });
                 // SRI must hash the bytes that ship: Vite only finalizes chunks (replacing markers like
                 // `__VITE_PRELOAD__`) when writing to disk, so the in-memory bundle differs from the file.
@@ -115,10 +127,15 @@ export const unpluginFactory: UnpluginFactory<Options | undefined> = (options, _
                         manifestKeyPrefix: resolved.manifestKeyPrefix,
                     };
                     try {
+                        const copyFiles = resolveCopyFiles(resolved.copy, false);
+                        writeCopyFiles(copyFiles, resolved.outputPath);
                         writeSymfonyFiles(
                             resolved.outputPath,
                             buildEntrypoints(configToDevGraph(server.config), ctx),
-                            {}
+                            copyManifest(copyFiles, {
+                                publicPath: resolved.publicPath,
+                                manifestKeyPrefix: resolved.manifestKeyPrefix,
+                            })
                         );
                     } catch (err) {
                         server.config.logger.error(

assets/src/rsbuild.ts

@@ -1,10 +1,11 @@
 import type { RsbuildPlugin } from '@rsbuild/core';
 import type { RspackStats } from './collectors/rspack';
-import type { BuildContext, Options } from './types';
+import type { BuildContext, ManifestJson, Options } from './types';
 import * as path from 'node:path';
 import * as process from 'node:process';
 import { rspack } from '@rsbuild/core';
 import { statsToGraph } from './collectors/rspack';
+import { copyManifest, resolveCopyFiles, writeCopyFiles } from './core/copy';
 import { writeSymfonyFiles } from './core/emit';
 import { integrityFromDisk, referencedFileNames } from './core/integrity';
 import { buildEntrypoints, buildManifest } from './core/format';
@@ -103,6 +104,32 @@ export default function symfony(options?: Options): RsbuildPlugin {
             api.onAfterCreateCompiler(({ compiler }) => {
                 const compilers = 'compilers' in compiler ? compiler.compilers : [compiler];
                 for (const c of compilers) {
+                    // Build: emit the copied files into the compilation, so Rspack writes them, lists
+                    // them in the build output, and cleans them like any other asset. `sourceFilename`
+                    // lets the existing statsToGraph collector key them in manifest.json (no manual
+                    // merge — see the `done` tap). Dev instead writes them to disk in `done`: there they
+                    // are served by the Symfony web server from `public/build`, not by the dev server,
+                    // so they must not become in-memory compilation assets.
+                    if (!isDev) {
+                        c.hooks.thisCompilation.tap('@symfony/reprise:copy', (compilation) => {
+                            compilation.hooks.processAssets.tap(
+                                {
+                                    name: '@symfony/reprise:copy',
+                                    stage: rspack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL,
+                                },
+                                () => {
+                                    for (const file of resolveCopyFiles(resolved.copy, true)) {
+                                        compilation.emitAsset(
+                                            file.physicalName,
+                                            new rspack.sources.RawSource(file.source),
+                                            { sourceFilename: file.logicalName }
+                                        );
+                                    }
+                                }
+                            );
+                        });
+                    }
+
                     c.hooks.done.tap('@symfony/reprise', (stats) => {
                         const isDev = c.watchMode;
                         // The dev URLs we advertise must be the dev-server origin joined with our `publicPath`
@@ -141,10 +168,22 @@ export default function symfony(options?: Options): RsbuildPlugin {
                                 resolved.integrity.algorithms
                             );
                         }
-                        // In dev the manifest is empty: assets are served from the dev server, never looked
-                        // up on disk by hash, so cache-busting is moot. entrypoints.json alone drives loading.
-                        // Matches the Vite dev path (see `configureServer` in index.ts), which also writes `{}`.
-                        const manifest = isDev ? {} : buildManifest(graph, ctx);
+                        // Copied static files: in build they were emitted into the compilation (see the
+                        // processAssets tap above), so statsToGraph already carries them in `graph.assets`
+                        // and `buildManifest` keys them. In dev they are not emitted (served by the Symfony
+                        // web server from disk, not the dev server), so write them out here and key them by
+                        // their relative publicPath URL.
+                        let manifest: ManifestJson;
+                        if (isDev) {
+                            const copyFiles = resolveCopyFiles(resolved.copy, false);
+                            writeCopyFiles(copyFiles, resolved.outputPath);
+                            manifest = copyManifest(copyFiles, {
+                                publicPath: resolved.publicPath,
+                                manifestKeyPrefix: resolved.manifestKeyPrefix,
+                            });
+                        } else {
+                            manifest = buildManifest(graph, ctx);
+                        }
                         try {
                             writeSymfonyFiles(resolved.outputPath, buildEntrypoints(graph, ctx), manifest);
                         } catch (err) {

assets/src/types.ts

@@ -98,6 +98,18 @@ export interface Options {
      * ```
      */
     integrity?: IntegrityOptions;
+
+    /**
+     * Copy static files (images, fonts…) into the build output and register them
+     * in manifest.json, so Twig's `asset('<to>/<path>')` resolves to the file URL.
+     * Works in both build (content-hashed names) and dev (verbatim names). Files are
+     * written under `outputPath` and served by the Symfony web server from `public/`.
+     *
+     * ```js
+     * Symfony({ copy: [{ from: 'assets/images', to: 'images' }] })
+     * ```
+     */
+    copy?: CopyEntry[];
 }
 
 /** Hash algorithm used for Subresource Integrity. */
@@ -124,6 +136,24 @@ export interface ResolvedStimulusOptions {
     controllersDir: string;
 }
 
+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`). */
+    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;
+}
+
+export interface ResolvedCopyEntry {
+    from: string;
+    to: string;
+    pattern: RegExp;
+    includeSubdirectories: boolean;
+}
+
 /** Map of Stimulus identifier -> controller class (registered eagerly). */
 export type EagerControllersCollection = Record<string, ControllerConstructor>;
 /** Map of Stimulus identifier -> dynamic-import factory (registered lazily). */
@@ -137,6 +167,7 @@ export interface ResolvedOptions {
     stimulus?: ResolvedStimulusOptions;
     /** Present (with a non-empty algorithm list) only when SRI is enabled. */
     integrity?: { algorithms: string[] };
+    copy: ResolvedCopyEntry[];
 }
 
 export interface EntryFiles {