feature #51 [Builds] Add support for multiple named builds (Kocal)

This PR was merged into the main branch.

Discussion
----------

[Builds] Add support for multiple named builds

| Q              | A
| -------------- | ---
| Bug fix?       | no
| New feature?   | yes
| Deprecations?  | no
| Documentation? | yes
| License        | MIT

This is Reprise's port of Webpack Encore's multi-build feature (Encore's `builds` config plus the `entrypointName` argument on tag functions). A single Symfony app can now drive several independent bundles at once: for example, a Vite-built public frontend and an Rsbuild-built admin panel, each with its own plugin config, output directory, and `entrypoints.json`. The default build continues to come from `output_path`; named builds are declared under a new `builds` key (a map of build name -> output directory). Setting `output_path: false` enables a named-builds-only setup, provided at least one build is declared (the bundle throws at container-compile time otherwise). The name `_default` is reserved.

Every Twig tag and file function (`reprise_entry_script_tags`, `reprise_entry_link_tags`, `reprise_entry_js_files`, `reprise_entry_css_files`) and `reprise_entry_exists` now accepts a `build` argument to select which build to look up; omitting it falls back to the default.

```twig
{{ reprise_entry_script_tags('app') }}
{{ reprise_entry_script_tags('dashboard', build='admin') }}
```

A few internals worth flagging for review: there is a new `EntrypointsLookupCollection` (backed by a service locator, behind a public `EntrypointsLookupCollectionInterface`) that resolves the per-build `EntrypointsLookup` service on demand, and a new `UndefinedBuildException` for unknown build names. The `TagRenderer` now resolves its lookup through that collection and tracks injected HMR clients as a set keyed by client URL, so two dev servers running simultaneously (Vite and Rsbuild) each inject their client exactly once. The reset listener was generalized to reset an `iterable<ResetInterface>` covering every build's lookup plus the renderer, and the cache warmer now warms one cache key per build. The `build` argument on Twig functions, previously introduced as a reserved placeholder that threw on use, is now fully functional.

No JS or plugin changes are needed: one bundler config already writes one `entrypoints.json` per output directory. The feature is covered by unit tests, a Vite+Rsbuild functional test, and config-validation tests, and documented in `doc/index.rst`.

Commits
-------

afb5bfa [Builds] Add support for multiple named builds

Author: Kocal

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Add a per-call `attributes` argument to the `reprise_entry_script_tags()` and `reprise_entry_link_tags()` Twig functions
 - Add the `reprise_entry_exists()` Twig function
+- Add support for multiple named builds via the `builds` config and a `build` argument on the Twig functions
 
 ## 0.5.0
 

README.md

@@ -30,6 +30,7 @@ Symfony Reprise covers only the Symfony-side glue the bundlers leave out:
 - 🔖 **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
+- 🧱 **Multiple builds**: drive several bundles (e.g. a main app and a separately-built embeddable widget) from one Symfony app
 - 🏷️ **Twig tag rendering**: `reprise_entry_script_tags`/`reprise_entry_link_tags` render straight from `entrypoints.json`
 - 🧩 **Symfony UX / Stimulus**: registers `controllers.json` and local controllers, eager or lazy
 - 🌐 **CDN support**: serve built assets from an absolute `publicPath`

config/cache.php

@@ -31,8 +31,7 @@
 
     $services->set('reprise.entrypoints_cache_warmer', EntrypointsCacheWarmer::class)
         ->args([
-            param('reprise.entrypoints_path'),
-            'reprise.entrypoints',
+            param('reprise.entrypoints_paths'),
             service('reprise.cache'),
         ])
         ->tag('kernel.cache_warmer')

doc/index.rst

@@ -17,6 +17,7 @@ reimplement any of that. It covers only the Symfony-side glue the bundlers leave
 - **Asset versioning**: content-hash cache busting, wired into the manifest
 - **File copy**: copy static files into the build, keyed in the manifest
 - **Dev server and HMR**: points Twig at the running Vite/Rsbuild server
+- **Multiple builds**: drive several bundles (e.g. a main app and a separately-built embeddable widget) from one Symfony app
 - **Twig tag rendering**: ``reprise_entry_script_tags``/``reprise_entry_link_tags`` render straight from
   ``entrypoints.json``
 - **Symfony UX / Stimulus**: registers ``controllers.json`` and local controllers, eager or lazy
@@ -456,6 +457,89 @@ The resulting ``entrypoints.json`` gets an extra ``integrity`` section:
 Hashes cover every referenced file in each entry (js, css, and preloaded/dynamic chunks), and since they're computed
 from the files actually written to disk, they stay correct through minification and hashing.
 
+Multiple builds
+~~~~~~~~~~~~~~~
+
+Several areas of one app (a public part, an admin panel) are usually just separate entry points in one config: the
+Multiple entries case, addressed by name without a ``build`` argument. Reach for multiple builds only when a part
+needs its own bundler config and output directory, like an embeddable widget built apart from the main app.
+
+Give the widget its own config, pointing the plugin at a separate output directory -> with Vite:
+
+.. code-block:: javascript
+
+    // vite.config.widget.ts  -- run with `vite build --config vite.config.widget.ts`
+    import { defineConfig } from 'vite'
+    import Symfony from '@symfony/reprise/vite'
+
+    export default defineConfig({
+      build: {
+        rolldownOptions: {
+          input: {
+            widget: './assets/widget.js',
+          },
+        },
+      },
+      plugins: [
+        Symfony({
+          outputPath: 'public/widget-build',
+          publicPath: '/widget-build/',
+        }),
+      ],
+    })
+
+or with Rsbuild:
+
+.. code-block:: javascript
+
+    // rsbuild.config.widget.ts  -- run with `rsbuild build --config rsbuild.config.widget.ts`
+    import { defineConfig } from '@rsbuild/core'
+    import Symfony from '@symfony/reprise/rsbuild'
+
+    export default defineConfig({
+      source: {
+        entry: {
+          widget: './assets/widget.js',
+        },
+      },
+      plugins: [
+        Symfony({
+          outputPath: 'public/widget-build',
+          publicPath: '/widget-build/',
+        }),
+      ],
+    })
+
+These two blocks are alternatives: pick the one that matches your bundler, you don't use both in one project.
+
+Name that directory in ``reprise.yaml``:
+
+.. code-block:: yaml
+
+    # config/packages/reprise.yaml
+    reprise:
+        # the main app (your existing config), addressed without a build name
+        output_path: '%kernel.project_dir%/public/build'
+        builds:
+            # each extra build: name -> the directory its entrypoints.json lives in
+            widget: '%kernel.project_dir%/public/widget-build'
+
+In Twig, pass the build name to load from it; omit it for the default build:
+
+.. code-block:: twig
+
+    {# the main app (default build) #}
+    {{ reprise_entry_script_tags('app') }}
+    {{ reprise_entry_link_tags('app') }}
+
+    {# the widget build, selected with the build argument #}
+    {{ reprise_entry_script_tags('widget', build='widget') }}
+    {{ reprise_entry_link_tags('widget', build='widget') }}
+
+The ``build`` argument works on every ``reprise_entry_*`` function. Each build has its own dev server, so the app's
+and the widget's can run at once on different ports, each injecting its HMR client once. Set ``output_path: false``
+for a named-builds-only setup (at least one build is required).
+
 Configuration
 -------------
 
@@ -466,8 +550,12 @@ Reprise exposes a few optional settings under its own configuration, all shown h
     # config/packages/reprise.yaml
     reprise:
         # Directory the @symfony/reprise plugin writes entrypoints.json and manifest.json into.
+        # Set to false when using only named builds (requires at least one entry under builds).
         output_path: '%kernel.project_dir%/public/build'
 
+        # Additional named builds: a map of build name -> output directory (see `Multiple builds`_).
+        builds: {}
+
         # Throw when entrypoints.json or a requested entry is missing, instead of rendering nothing.
         strict_mode: true
 
@@ -488,7 +576,10 @@ Reprise exposes a few optional settings under its own configuration, all shown h
         link_attributes: []
 
 - ``output_path``: filesystem directory holding ``entrypoints.json`` and ``manifest.json``. Must match the plugin's
-  own ``outputPath``.
+  own ``outputPath``. Accepts ``false`` to disable the default build entirely (requires at least one entry under
+  ``builds``).
+- ``builds``: a map of build name -> output directory for additional bundles. Each named build is addressed by passing
+  ``build='<name>'`` to the tag and file functions. See `Multiple builds`_.
 - ``strict_mode``: when ``true`` (the default), throws a clear exception on a missing file or an unknown entry; when
   ``false``, renders nothing instead.
 - ``cache``: when ``true``, parse ``entrypoints.json`` once at ``cache:warmup`` and read it from a compiled PHP file

src/Asset/EntrypointsLookupCollection.php

@@ -0,0 +1,47 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Reprise\Asset;
+
+use Symfony\Contracts\Service\ServiceProviderInterface;
+use Symfony\Reprise\Exception\UndefinedBuildException;
+
+/**
+ * @author Hugo Alliaume <hugo@alliau.me>
+ *
+ * @internal
+ */
+final class EntrypointsLookupCollection implements EntrypointsLookupCollectionInterface
+{
+    /**
+     * @param ServiceProviderInterface<EntrypointsLookupInterface> $lookups a service locator keyed by build name (the default build under "_default")
+     */
+    public function __construct(
+        private readonly ServiceProviderInterface $lookups,
+        private readonly ?string $defaultBuildName = null,
+    ) {
+    }
+
+    public function getEntrypointsLookup(?string $build = null): EntrypointsLookupInterface
+    {
+        $build ??= $this->defaultBuildName;
+
+        if (null === $build) {
+            throw new UndefinedBuildException('There is no default build configured: set "reprise.output_path", or pass an explicit build name.');
+        }
+
+        if (!$this->lookups->has($build)) {
+            throw new UndefinedBuildException(\sprintf('The build "%s" is not configured under "reprise.builds".', $build));
+        }
+
+        return $this->lookups->get($build);
+    }
+}

src/Asset/EntrypointsLookupCollectionInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Reprise\Asset;
+
+use Symfony\Reprise\Exception\UndefinedBuildException;
+
+/**
+ * Resolves the EntrypointsLookup for a named build (or the default build when none is given).
+ *
+ * @author Hugo Alliaume <hugo@alliau.me>
+ */
+interface EntrypointsLookupCollectionInterface
+{
+    /**
+     * @throws UndefinedBuildException when the build is unknown, or when null is given and no default build exists
+     */
+    public function getEntrypointsLookup(?string $build = null): EntrypointsLookupInterface;
+}

src/Asset/TagRenderer.php

@@ -27,14 +27,20 @@
  */
 final class TagRenderer implements ResetInterface
 {
-    private bool $clientInjected = false;
+    /**
+     * HMR client URLs already injected this request, kept as a set so each dev server (there is one per
+     * build) injects its client exactly once, even when several builds render on the same page.
+     *
+     * @var array<string, true>
+     */
+    private array $injectedClients = [];
 
     /**
      * @param array<string, bool|string> $scriptAttributes
      * @param array<string, bool|string> $linkAttributes
      */
     public function __construct(
-        private readonly EntrypointsLookupInterface $lookup,
+        private readonly EntrypointsLookupCollectionInterface $collection,
         private readonly Packages $packages,
         private readonly ?RequestStack $requestStack = null,
         private readonly ?string $defaultPackage = null,
@@ -51,28 +57,28 @@ public function __construct(
      */
     public function renderScriptTags(string $entryName, ?string $packageName = null, ?string $build = null, array $attributes = []): string
     {
-        $this->assertNoBuild($build);
-        $integrity = $this->lookup->getIntegrityData();
+        $lookup = $this->collection->getEntrypointsLookup($build);
+        $integrity = $lookup->getIntegrityData();
         $tags = [];
 
-        $devServer = $this->lookup->getDevServer();
-        if (!$this->clientInjected && null !== $devServer && null !== $devServer->client) {
+        $devServer = $lookup->getDevServer();
+        if (null !== $devServer && null !== $devServer->client && !isset($this->injectedClients[$devServer->client])) {
             $tags[] = \sprintf('<script type="module" src="%s"></script>', htmlspecialchars($devServer->client, \ENT_QUOTES));
             if (null !== $devServer->reactRefresh) {
                 $tags[] = $this->renderReactRefreshPreamble($devServer->reactRefresh);
             }
-            $this->clientInjected = true;
+            $this->injectedClients[$devServer->client] = true;
         }
 
-        foreach ($this->lookup->getPreloadFiles($entryName) as $reference) {
+        foreach ($lookup->getPreloadFiles($entryName) as $reference) {
             $url = $this->url($reference, $packageName);
             $tagAttributes = ['rel' => 'modulepreload', 'href' => $url];
             $this->applyIntegrity($tagAttributes, $reference, $integrity);
             $tags[] = \sprintf('<link %s>', $this->attributes($tagAttributes));
             $this->preload($url, 'modulepreload');
         }
 
-        foreach ($this->lookup->getJavaScriptFiles($entryName) as $reference) {
+        foreach ($lookup->getJavaScriptFiles($entryName) as $reference) {
             $url = $this->url($reference, $packageName);
             $tagAttributes = ['src' => $url, 'type' => 'module'] + $attributes + $this->scriptAttributes;
             $this->applyIntegrity($tagAttributes, $reference, $integrity);
@@ -89,10 +95,10 @@ public function renderScriptTags(string $entryName, ?string $packageName = null,
      */
     public function renderLinkTags(string $entryName, ?string $packageName = null, ?string $build = null, array $attributes = []): string
     {
-        $this->assertNoBuild($build);
-        $integrity = $this->lookup->getIntegrityData();
+        $lookup = $this->collection->getEntrypointsLookup($build);
+        $integrity = $lookup->getIntegrityData();
         $tags = [];
-        foreach ($this->lookup->getCssFiles($entryName) as $reference) {
+        foreach ($lookup->getCssFiles($entryName) as $reference) {
             $url = $this->url($reference, $packageName);
             $tagAttributes = ['rel' => 'stylesheet', 'href' => $url] + $attributes + $this->linkAttributes;
             $this->applyIntegrity($tagAttributes, $reference, $integrity);
@@ -106,27 +112,27 @@ public function renderLinkTags(string $entryName, ?string $packageName = null, ?
     /**
      * @return list<string>
      */
-    public function getJsFiles(string $entryName, ?string $packageName = null): array
+    public function getJsFiles(string $entryName, ?string $packageName = null, ?string $build = null): array
     {
-        return array_map(fn (string $r) => $this->url($r, $packageName), $this->lookup->getJavaScriptFiles($entryName));
+        return array_map(fn (string $r) => $this->url($r, $packageName), $this->collection->getEntrypointsLookup($build)->getJavaScriptFiles($entryName));
     }
 
     /**
      * @return list<string>
      */
-    public function getCssFiles(string $entryName, ?string $packageName = null): array
+    public function getCssFiles(string $entryName, ?string $packageName = null, ?string $build = null): array
     {
-        return array_map(fn (string $r) => $this->url($r, $packageName), $this->lookup->getCssFiles($entryName));
+        return array_map(fn (string $r) => $this->url($r, $packageName), $this->collection->getEntrypointsLookup($build)->getCssFiles($entryName));
     }
 
-    public function entryExists(string $entryName): bool
+    public function entryExists(string $entryName, ?string $build = null): bool
     {
-        return $this->lookup->entryExists($entryName);
+        return $this->collection->getEntrypointsLookup($build)->entryExists($entryName);
     }
 
     public function reset(): void
     {
-        $this->clientInjected = false;
+        $this->injectedClients = [];
     }
 
     /**
@@ -150,13 +156,6 @@ private function renderReactRefreshPreamble(string $reactRefreshUrl): string
         );
     }
 
-    private function assertNoBuild(?string $build): void
-    {
-        if (null !== $build) {
-            throw new \InvalidArgumentException(\sprintf('No build named "%s" is configured.', $build));
-        }
-    }
-
     private function url(string $reference, ?string $packageName): string
     {
         return $this->packages->getUrl($reference, $packageName ?? $this->defaultPackage);

src/CacheWarmer/EntrypointsCacheWarmer.php

@@ -25,9 +25,11 @@
  */
 final class EntrypointsCacheWarmer implements CacheWarmerInterface
 {
+    /**
+     * @param array<string, string> $entrypointsPaths build name => entrypoints.json path
+     */
     public function __construct(
-        private readonly string $entrypointsPath,
-        private readonly string $cacheKey,
+        private readonly array $entrypointsPaths,
         private readonly PhpArrayAdapter $cache,
     ) {
     }
@@ -39,17 +41,24 @@ public function isOptional(): bool
 
     public function warmUp(string $cacheDir, ?string $buildDir = null): array
     {
-        if (!is_file($this->entrypointsPath)) {
-            return [];
-        }
+        $values = [];
+        foreach ($this->entrypointsPaths as $build => $path) {
+            if (!is_file($path)) {
+                continue;
+            }
 
-        try {
-            $decoded = json_decode((string) file_get_contents($this->entrypointsPath), true, flags: \JSON_THROW_ON_ERROR);
-            if (\is_array($decoded)) {
-                $this->cache->warmUp([$this->cacheKey => Entrypoints::fromArray($decoded)]);
+            try {
+                $decoded = json_decode((string) file_get_contents($path), true, flags: \JSON_THROW_ON_ERROR);
+                if (\is_array($decoded)) {
+                    $values['reprise.entrypoints.'.$build] = Entrypoints::fromArray($decoded);
+                }
+            } catch (\Throwable) {
+                // A malformed entrypoints.json at deploy time must not break cache:warmup.
             }
-        } catch (\Throwable) {
-            // A malformed entrypoints.json at deploy time must not break cache:warmup.
+        }
+
+        if ($values) {
+            $this->cache->warmUp($values);
         }
 
         return [];