|
| 1 | +Symfony Reprise |
| 2 | +=============== |
| 3 | + |
| 4 | +**EXPERIMENTAL** This bundle is experimental and is likely to change, |
| 5 | +or even change drastically. |
| 6 | + |
| 7 | +Webpack Encore gave Symfony first-class asset integration for Webpack. |
| 8 | +Symfony Reprise gives you the same integration for `Vite`_ and `Rsbuild`_. |
| 9 | + |
| 10 | +Vite and Rsbuild already handle **Sass/Less/PostCSS**, **TypeScript**, |
| 11 | +**JSX/Vue/Svelte**, **code splitting**, **content hashing**, **source maps**, |
| 12 | +**minification** and **HMR** on their own, so Symfony Reprise does not |
| 13 | +reimplement any of that. It only covers the Symfony-side integration that |
| 14 | +bundlers do not provide out of the box: |
| 15 | + |
| 16 | +- Multiple entries |
| 17 | +- ``entrypoints.json`` generation (build and dev-server modes) |
| 18 | +- ``manifest.json`` generation |
| 19 | +- Asset versioning wired into the manifest |
| 20 | +- CDN support (absolute ``publicPath``) *(planned)* |
| 21 | +- Dev server and HMR integration |
| 22 | +- Subresource Integrity (SRI) hashes *(planned)* |
| 23 | +- Shared runtime chunk across entries *(planned)* |
| 24 | +- Symfony UX / Stimulus controllers (``controllers.json`` and local |
| 25 | + ``assets/controllers/``) |
| 26 | + |
| 27 | +Installation |
| 28 | +------------ |
| 29 | + |
| 30 | +Install the bundle with Composer and Symfony Flex: |
| 31 | + |
| 32 | +.. code-block:: terminal |
| 33 | +
|
| 34 | + $ composer require symfony/reprise |
| 35 | +
|
| 36 | +Then install the npm package: |
| 37 | + |
| 38 | +.. code-block:: terminal |
| 39 | +
|
| 40 | + $ npm install @symfony/reprise --save-dev |
| 41 | +
|
| 42 | +Vite |
| 43 | +---- |
| 44 | + |
| 45 | +.. code-block:: javascript |
| 46 | +
|
| 47 | + // vite.config.ts |
| 48 | + import { defineConfig } from 'vite' |
| 49 | + import Symfony from '@symfony/reprise/vite' |
| 50 | +
|
| 51 | + export default defineConfig({ |
| 52 | + plugins: [ |
| 53 | + Symfony({ /* options */ }), |
| 54 | + ], |
| 55 | + }) |
| 56 | +
|
| 57 | +Rsbuild |
| 58 | +------- |
| 59 | + |
| 60 | +.. code-block:: javascript |
| 61 | +
|
| 62 | + // rsbuild.config.ts |
| 63 | + import { defineConfig } from '@rsbuild/core' |
| 64 | + import Symfony from '@symfony/reprise/rsbuild' |
| 65 | +
|
| 66 | + export default defineConfig({ |
| 67 | + plugins: [Symfony({ /* options */ })], |
| 68 | + }) |
| 69 | +
|
| 70 | +Symfony UX / Stimulus controllers |
| 71 | +--------------------------------- |
| 72 | + |
| 73 | +This is the Vite/Rsbuild counterpart of what `@symfony/stimulus-bridge`_ did |
| 74 | +for Webpack Encore: it turns your ``controllers.json`` into a Stimulus |
| 75 | +application, with the same enable step, same helper, same local-controllers |
| 76 | +convention. |
| 77 | + |
| 78 | +Enable it by pointing the plugin at your ``controllers.json`` (this is what |
| 79 | +turns the feature on): |
| 80 | + |
| 81 | +.. code-block:: javascript |
| 82 | +
|
| 83 | + Symfony({ |
| 84 | + stimulus: 'assets/controllers.json', |
| 85 | + }) |
| 86 | + // or, to override the local controllers dir: |
| 87 | + Symfony({ |
| 88 | + stimulus: { |
| 89 | + controllersJson: 'assets/controllers.json', |
| 90 | + controllersDir: 'assets/controllers', |
| 91 | + }, |
| 92 | + }) |
| 93 | +
|
| 94 | +Then start the app from your entry: |
| 95 | + |
| 96 | +.. code-block:: javascript |
| 97 | +
|
| 98 | + import { startStimulusApp } from '@symfony/reprise/stimulus' |
| 99 | +
|
| 100 | + const app = startStimulusApp() |
| 101 | +
|
| 102 | +**Local controllers.** Any ``assets/controllers/*_controller.{js,ts}`` is |
| 103 | +registered automatically. The filename becomes the identifier |
| 104 | +(``hello_controller.js`` becomes ``hello``, ``admin/user_controller.js`` |
| 105 | +becomes ``admin--user``). To load a controller on demand, put a |
| 106 | +``stimulusFetch: 'lazy'`` comment directly above the class (after the |
| 107 | +imports) — a block or a single-line comment both work: |
| 108 | + |
| 109 | +.. code-block:: javascript |
| 110 | +
|
| 111 | + import { Controller } from '@hotwired/stimulus' |
| 112 | +
|
| 113 | + /* stimulusFetch: 'lazy' */ |
| 114 | + export default class extends Controller {} |
| 115 | +
|
| 116 | +(``// stimulusFetch: 'lazy'`` on the line above the class works too.) |
| 117 | + |
| 118 | +**Third-party UX packages.** Controllers declared in ``controllers.json`` are |
| 119 | +resolved from ``node_modules``, so install them with your package manager, the |
| 120 | +same as you would with Webpack Encore: |
| 121 | + |
| 122 | +.. code-block:: terminal |
| 123 | +
|
| 124 | + $ npm install @hotwired/stimulus @symfony/ux-turbo @symfony/ux-leaflet-map |
| 125 | +
|
| 126 | +Some packages need a bit of bundler-specific setup on top, the same way they |
| 127 | +did under Webpack Encore. UX Leaflet Map, for instance, ships a CSS file meant |
| 128 | +for Webpack's loader and needs an alias to the plain CSS build: |
| 129 | + |
| 130 | +.. code-block:: javascript |
| 131 | +
|
| 132 | + // vite.config.ts |
| 133 | + export default defineConfig({ |
| 134 | + resolve: { |
| 135 | + alias: { |
| 136 | + 'leaflet/dist/leaflet.min.css': 'leaflet/dist/leaflet.css', |
| 137 | + }, |
| 138 | + }, |
| 139 | + }) |
| 140 | +
|
| 141 | +Check each package's own docs for this kind of tweak. |
| 142 | + |
| 143 | +.. _Vite: https://vite.dev/ |
| 144 | +.. _Rsbuild: https://rsbuild.dev/ |
| 145 | +.. _`@symfony/stimulus-bridge`: https://github.com/symfony/stimulus-bridge |
0 commit comments