Skip to content

Commit d833c5a

Browse files
KocalKocal
committed
tidy #3 [Docs] Move usage documentation to doc/index.rst (Kocal)
This PR was merged into the main branch. Discussion ---------- [Docs] Move usage documentation to doc/index.rst | Q | A | ------------- | --- | Bug fix? | no | New feature? | no | Deprecations? | no | Issues | Fix #... <!-- prefix each issue number with "Fix #", no need to open an issue if none exists, explain below instead --> | License | MIT <!-- Replace this notice with a description of your feature or bugfix. This helps reviewers and is a good starting point for the documentation. Additionally (see https://symfony.com/releases): - Always add tests and ensure they pass. - For new features, provide some code snippets to help understand usage. - Features and deprecations must be submitted against the main branch. - Update or add documentation as required (we can help!). - Never break backward compatibility (see https://symfony.com/bc). --> Commits ------- 885e20f [Docs] Move usage documentation to doc/index.rst
2 parents 137d261 + 885e20f commit d833c5a

2 files changed

Lines changed: 148 additions & 106 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -4,111 +4,8 @@
44
[![npm downloads](https://img.shields.io/npm/dm/@symfony%2Freprise?color=crimson&label=)](https://www.npmjs.com/package/@symfony/reprise)
55
[![license](https://img.shields.io/npm/l/@symfony%2Freprise?color=crimson&label=)](https://www.npmjs.com/package/@symfony/reprise)
66

7-
Webpack Encore gave Symfony first-class asset integration for Webpack. Symfony Reprise gives you the same integration for **Vite** and **Rsbuild**.
8-
9-
## Features
10-
11-
⚡️Vite and 🦀Rsbuild already handle **Sass/Less/PostCSS**, **TypeScript**, **JSX/Vue/Svelte**, **code splitting**, **content hashing**, **source maps**, **minification** and **HMR** on their own, so Symfony Reprise doesn't reimplement any of that.
12-
It only covers the Symfony-side integration that bundlers don't provide out of the box:
13-
14-
- [x] Multiple entries
15-
- [x] `entrypoints.json` generation (build + dev-server modes)
16-
- [x] `manifest.json` generation
17-
- [x] Asset versioning wired into the manifest
18-
- [ ] CDN support (absolute `publicPath`)
19-
- [x] Dev server & HMR integration
20-
- [ ] Subresource Integrity (SRI) hashes
21-
- [ ] Shared runtime chunk across entries
22-
- [x] Symfony UX / Stimulus controllers (`controllers.json` + local `assets/controllers/`)
23-
24-
## Install
25-
26-
```bash
27-
npm install @symfony/reprise --save-dev
28-
```
29-
30-
<details>
31-
<summary>Vite</summary><br>
32-
33-
```ts
34-
// vite.config.ts
35-
import { defineConfig } from 'vite'
36-
import Symfony from '@symfony/reprise/vite'
37-
38-
export default defineConfig({
39-
plugins: [
40-
Symfony({ /* options */}),
41-
],
42-
})
43-
```
44-
45-
Example: [`playground/`](./playground/)
46-
47-
<br></details>
48-
49-
<details>
50-
<summary>Rsbuild</summary><br>
51-
52-
```ts
53-
// rsbuild.config.ts
54-
import { defineConfig } from '@rsbuild/core'
55-
import Symfony from '@symfony/reprise/rsbuild'
56-
57-
export default defineConfig({
58-
plugins: [Symfony({ /* options */ })],
59-
})
60-
```
61-
62-
<br></details>
7+
**EXPERIMENTAL** This bundle is experimental and is likely to change, or even change drastically.
638

64-
## Symfony UX / Stimulus controllers
65-
66-
This is the Vite/Rsbuild counterpart of what `@symfony/stimulus-bridge` did for Webpack Encore: it turns your `controllers.json` into a Stimulus application, with the same enable step, same helper, same local-controllers convention.
67-
68-
Enable it by pointing the plugin at your `controllers.json` (this is what turns the feature on):
69-
70-
```ts
71-
Symfony({ stimulus: 'assets/controllers.json' })
72-
// or, to override the local controllers dir:
73-
Symfony({ stimulus: { controllersJson: 'assets/controllers.json', controllersDir: 'assets/controllers' } })
74-
```
75-
76-
Then start the app from your entry:
77-
78-
```ts
79-
import { startStimulusApp } from '@symfony/reprise/stimulus'
80-
81-
const app = startStimulusApp()
82-
```
83-
84-
**Local controllers.** Any `assets/controllers/*_controller.{js,ts}` is registered automatically. The filename becomes the identifier (`hello_controller.js` -> `hello`, `admin/user_controller.js` -> `admin--user`). To load a controller on demand, put a `stimulusFetch: 'lazy'` comment directly above the class (after the imports) — a block or a single-line comment both work:
85-
86-
```js
87-
import { Controller } from '@hotwired/stimulus'
88-
89-
/* stimulusFetch: 'lazy' */
90-
export default class extends Controller {}
91-
```
92-
93-
(`// stimulusFetch: 'lazy'` on the line above the class works too. The marker only counts directly above the class — not above the imports.)
94-
95-
**Third-party UX packages.** Controllers declared in `controllers.json` are resolved from `node_modules`, so install them with your package manager, same as you would with Webpack Encore (AssetMapper instead vendors them via importmap):
96-
97-
```bash
98-
npm install @hotwired/stimulus @symfony/ux-turbo @symfony/ux-leaflet-map
99-
```
100-
101-
Some packages need a bit of bundler-specific setup on top, the same way they did under Webpack Encore. UX Leaflet Map, for instance, ships a CSS file meant for Webpack's loader and needs an alias to the plain CSS build:
102-
103-
```ts
104-
// vite.config.ts
105-
export default defineConfig({
106-
resolve: {
107-
alias: {
108-
'leaflet/dist/leaflet.min.css': 'leaflet/dist/leaflet.css',
109-
},
110-
},
111-
})
112-
```
9+
Webpack Encore gave Symfony first-class asset integration for Webpack. Symfony Reprise gives you the same integration for **Vite** and **Rsbuild**.
11310

114-
Check each package's own docs for this kind of tweak.
11+
[Read the documentation](doc/index.rst)

‎doc/index.rst‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
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

Comments
 (0)