@nodefony/frontend 10.0.0-beta.1 → 10.0.0-beta.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +56 -68
- package/dist/_virtual/{_@oxc-project_runtime@0.151.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorate.js +1 -1
- package/dist/_virtual/{_@oxc-project_runtime@0.151.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorateMetadata.js +1 -1
- package/dist/index.js +2 -2
- package/dist/nodefony/config/config.js +3 -8
- package/dist/nodefony/service/FrontendService.js +73 -295
- package/dist/nodefony/service/ViteConfigGenerator.js +11 -30
- package/dist/nodefony/service/ViteProcessSupervisor.js +17 -12
- package/dist/nodefony/service/bootSummary.js +44 -0
- package/dist/nodefony/src/isolationGroups.js +27 -32
- package/dist/nodefony/src/template/TemplateHelper.js +52 -19
- package/dist/types/nodefony/config/config.d.ts +0 -8
- package/dist/types/nodefony/interfaces/IFrontBuilder.d.ts +0 -9
- package/dist/types/nodefony/interfaces/IFrontendService.d.ts +6 -10
- package/dist/types/nodefony/interfaces/IViteSupervisor.d.ts +11 -5
- package/dist/types/nodefony/service/FrontendService.d.ts +24 -118
- package/dist/types/nodefony/service/ViteConfigGenerator.d.ts +13 -21
- package/dist/types/nodefony/service/ViteProcessSupervisor.d.ts +13 -16
- package/dist/types/nodefony/service/bootSummary.d.ts +23 -0
- package/dist/types/nodefony/src/isolationGroups.d.ts +24 -23
- package/dist/types/nodefony/src/template/TemplateHelper.d.ts +23 -7
- package/docs/index.md +173 -145
- package/package.json +12 -13
- package/dist/nodefony/src/remoteDev.js +0 -216
- package/dist/types/nodefony/src/remoteDev.d.ts +0 -152
package/docs/index.md
CHANGED
|
@@ -10,7 +10,7 @@ tags:
|
|
|
10
10
|
[frontend, vite, hmr, react, vue, angular, build, bundle, manifest, csp, cdn]
|
|
11
11
|
version: "doc"
|
|
12
12
|
status: stable
|
|
13
|
-
updated: 2026-
|
|
13
|
+
updated: 2026-10-03
|
|
14
14
|
source: "src/packages/@nodefony/frontend/docs/index.md"
|
|
15
15
|
coverageModule: frontend
|
|
16
16
|
---
|
|
@@ -30,22 +30,26 @@ coverageModule: frontend
|
|
|
30
30
|
|
|
31
31
|
Le réflexe habituel est de croire qu'un projet front et un projet back sont deux applications. Ici,
|
|
32
32
|
il n'y en a qu'une : ton module Nodefony **déclare** son interface, et le module frontend s'occupe du
|
|
33
|
-
reste. Concrètement, deux serveurs tournent en développement
|
|
33
|
+
reste. Concrètement, deux serveurs tournent en développement, mais le navigateur n'en voit qu'**un**.
|
|
34
34
|
|
|
35
35
|
```mermaid
|
|
36
36
|
flowchart TD
|
|
37
|
-
BR["Navigateur"] -->|1 · GET /shop| NF["Nodefony ·
|
|
38
|
-
NF -->|2 · HTML + balises script| BR
|
|
39
|
-
BR -->|3 ·
|
|
40
|
-
|
|
41
|
-
|
|
37
|
+
BR["Navigateur"] -->|1 · GET /shop| NF["Nodefony · 5152<br/>route → contrôleur → HTML"]
|
|
38
|
+
NF -->|2 · HTML + balises script relatives| BR
|
|
39
|
+
BR -->|3 · /_vite/… modules, styles, HMR| NF
|
|
40
|
+
NF -->|relais sur la boucle locale| VITE["Vite · 127.0.0.1:5173<br/>processus séparé"]
|
|
41
|
+
BR -->|4 · fetch /shop/api| NF
|
|
42
42
|
NF -.->|spawn au démarrage<br/>arrêt au terminate| VITE
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
Lis le schéma comme une visite : la **page** vient
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
45
|
+
Lis le schéma comme une visite : la **page** vient de Nodefony (1-2) ; les **modules JavaScript**,
|
|
46
|
+
les styles et le socket du rechargement à chaud passent eux aussi par Nodefony, sous le chemin
|
|
47
|
+
réservé `/_vite/<famille>/`, que le [proxy inverse](../../http/docs/reverse-proxy.md) relaie à Vite
|
|
48
|
+
(3) ; et les **appels d'API** arrivent à Nodefony comme n'importe quelle requête (4). Vite reste sur
|
|
49
|
+
la boucle locale, le navigateur ne le joint jamais : **une seule origine, un seul certificat**. C'est
|
|
50
|
+
ce qui permet d'ouvrir l'application depuis un téléphone ou un conteneur en HTTPS — voir
|
|
51
|
+
[Hors de la boucle locale](#-hors-de-la-boucle-locale--téléphone-conteneur-réseau). En production,
|
|
52
|
+
Vite disparaît : les assets sont pré-construits et servis en fichiers statiques.
|
|
49
53
|
|
|
50
54
|
## 📖 Lexique
|
|
51
55
|
|
|
@@ -84,14 +88,14 @@ qui remplace Vite une fois en production.
|
|
|
84
88
|
### La vision Nodefony — ce que ce module fait différemment
|
|
85
89
|
|
|
86
90
|
**Vite est un processus système, pas une bibliothèque.** Le superviseur lance le binaire Vite avec
|
|
87
|
-
`child_process.spawn` (`ViteProcessSupervisor.attemptSpawn()`, `ViteProcessSupervisor.ts:
|
|
91
|
+
`child_process.spawn` (`ViteProcessSupervisor.attemptSpawn()`, `ViteProcessSupervisor.ts:421`). La
|
|
88
92
|
conséquence est concrète : compiler dix mille modules ne coûte **rien** à la latence de tes requêtes,
|
|
89
93
|
et un plantage de Vite ne tue pas ton serveur — le superviseur le relance tout seul.
|
|
90
94
|
|
|
91
95
|
**C'est Nodefony qui sert le HTML.** Beaucoup de piles séparent un serveur front (qui rend la page) et
|
|
92
96
|
un serveur d'API (qui rend le JSON). Ici, la page d'entrée reste une route de ton contrôleur :
|
|
93
97
|
elle traverse le pare-feu, connaît la session, reçoit son nonce CSP. Le module se contente d'y
|
|
94
|
-
**injecter les bonnes balises** (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts:
|
|
98
|
+
**injecter les bonnes balises** (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts:200`).
|
|
95
99
|
|
|
96
100
|
**Un seul Vite pour N modules.** Trois modules à interface ne lancent pas trois serveurs Vite : leurs
|
|
97
101
|
entrées sont agrégées dans une seule instance multi-entrées. La seule exception est documentée et
|
|
@@ -112,8 +116,8 @@ chaque étape suppose la précédente.
|
|
|
112
116
|
1. [Démarrage rapide](#-démarrage-rapide) — un module, une entrée, une page. Copie-colle, ça marche.
|
|
113
117
|
2. [`registerEntry`](#registerentry--la-déclaration-dune-interface) — les sept champs de la
|
|
114
118
|
déclaration, et lesquels comptent vraiment.
|
|
115
|
-
3. [
|
|
116
|
-
|
|
119
|
+
3. [Le relais `/_vite/`](#le-relais--une-origine-pour-tout) — pourquoi la page, ses modules et
|
|
120
|
+
son socket partagent une seule origine, et ce que ça t'épargne.
|
|
117
121
|
4. [Pièges](#-pièges) — les symptômes qu'on rencontre dans l'ordre où on les rencontre.
|
|
118
122
|
|
|
119
123
|
**Je pars en production** — ce qui change quand Vite n'est plus là.
|
|
@@ -139,25 +143,25 @@ chaque étape suppose la précédente.
|
|
|
139
143
|
|
|
140
144
|
Le tableau pour situer en cinq secondes ; les fiches en dessous pour savoir quoi lire.
|
|
141
145
|
|
|
142
|
-
| Brique | Ce qu'elle résout | Tu en as besoin quand…
|
|
143
|
-
| ------------------------------------------------------------------------- | --------------------------------------------------- |
|
|
144
|
-
| [`registerEntry`](#registerentry--la-déclaration-dune-interface) | déclarer qu'un module a une interface | toujours — c'est le point de contact
|
|
145
|
-
| [
|
|
146
|
-
| [Presets](#-extension) | brancher React, Vue, Angular ou du TypeScript nu | tu choisis ton framework UI
|
|
147
|
-
| [Familles d'isolation](#familles-disolation--pourquoi-angular-a-son-vite) | faire cohabiter plusieurs frameworks | tu mélanges Angular avec autre chose
|
|
148
|
-
| [Rendu des balises](#rendu--des-balises-ou-un-document-complet) | injecter le front dans une page servie par Nodefony | tu écris le contrôleur de la page
|
|
149
|
-
| [Modes de livraison](#-les-deux-modes-de-livraison-de-linterface) | Vite en dev, assets pré-construits ailleurs | tu déploies, ou tu publies un module
|
|
150
|
-
| [Build de production](#construire-pour-la-production--frontendbuild) | compiler, empreinter, produire le manifeste | tu prépares une image ou un paquet
|
|
151
|
-
| [Résilience](#résilience--ce-qui-se-passe-quand-vite-tombe) | survivre à un crash, un port occupé, un gel | ton poste n'est pas un labo aseptisé
|
|
146
|
+
| Brique | Ce qu'elle résout | Tu en as besoin quand… |
|
|
147
|
+
| ------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------ |
|
|
148
|
+
| [`registerEntry`](#registerentry--la-déclaration-dune-interface) | déclarer qu'un module a une interface | toujours — c'est le point de contact |
|
|
149
|
+
| [Le relais `/_vite/`](#le-relais--une-origine-pour-tout) | une origine pour la page, les modules et le socket | toujours en dev — rien à déclarer |
|
|
150
|
+
| [Presets](#-extension) | brancher React, Vue, Angular ou du TypeScript nu | tu choisis ton framework UI |
|
|
151
|
+
| [Familles d'isolation](#familles-disolation--pourquoi-angular-a-son-vite) | faire cohabiter plusieurs frameworks | tu mélanges Angular avec autre chose |
|
|
152
|
+
| [Rendu des balises](#rendu--des-balises-ou-un-document-complet) | injecter le front dans une page servie par Nodefony | tu écris le contrôleur de la page |
|
|
153
|
+
| [Modes de livraison](#-les-deux-modes-de-livraison-de-linterface) | Vite en dev, assets pré-construits ailleurs | tu déploies, ou tu publies un module |
|
|
154
|
+
| [Build de production](#construire-pour-la-production--frontendbuild) | compiler, empreinter, produire le manifeste | tu prépares une image ou un paquet |
|
|
155
|
+
| [Résilience](#résilience--ce-qui-se-passe-quand-vite-tombe) | survivre à un crash, un port occupé, un gel | ton poste n'est pas un labo aseptisé |
|
|
152
156
|
|
|
153
157
|
```nodefony-cards
|
|
154
158
|
[
|
|
155
159
|
{ "icon": "📝", "title": "registerEntry", "href": "#registerentry--la-déclaration-dune-interface",
|
|
156
|
-
"desc": "Le point de contact unique du module. Un module l'appelle dans son onKernelBoot et dit
|
|
160
|
+
"desc": "Le point de contact unique du module. Un module l'appelle dans son onKernelBoot et dit deux choses : quel framework et quel fichier d'entrée. Tout le reste a un défaut sensé.",
|
|
157
161
|
"meta": "la seule API que la plupart des applications toucheront jamais" },
|
|
158
|
-
{ "icon": "🔀", "title": "
|
|
159
|
-
"desc": "En développement
|
|
160
|
-
"meta": "à
|
|
162
|
+
{ "icon": "🔀", "title": "Relais /_vite/", "href": "#le-relais--une-origine-pour-tout",
|
|
163
|
+
"desc": "En développement, Nodefony relaie à Vite tout ce qui passe sous /_vite/<famille>/ — modules, styles, images, socket du rechargement à chaud. Une origine, un certificat : pas de contenu mixte ni de CORS, et la page s'ouvre en HTTPS depuis un téléphone ou un conteneur.",
|
|
164
|
+
"meta": "rien à déclarer — c'est ce qui rend le HTTPS de dev simple" },
|
|
161
165
|
{ "icon": "🎨", "title": "Presets", "href": "#-extension",
|
|
162
166
|
"desc": "Cinq recettes prêtes — React, Vue, Angular, Svelte, vanilla : quel greffon Vite charger, quelles dépendances pré-empaqueter, quelles extensions reconnaître. Les greffons sont chargés paresseusement : tu ne paies pas React si tu fais du Vue.",
|
|
163
167
|
"meta": "tu choisis ton framework UI, ou tu en ajoutes un" },
|
|
@@ -198,10 +202,8 @@ export default defineConfig(() => ({
|
|
|
198
202
|
// Le builder AVANT ses consommateurs : les modules à interface résolvent le
|
|
199
203
|
// service `frontend` dans leur onKernelBoot() — il doit déjà être enregistré.
|
|
200
204
|
use("@nodefony/frontend", {
|
|
201
|
-
// Tout est optionnel.
|
|
202
|
-
//
|
|
203
|
-
// contenu mixte page sécurisée ↔ modules en clair).
|
|
204
|
-
https: false,
|
|
205
|
+
// Tout est optionnel. Rien à régler pour le HTTPS : les modules passent
|
|
206
|
+
// par l'origine de la page, donc par le certificat de Nodefony.
|
|
205
207
|
viteEnv: { VITE_API_BASE: "/shop/api" },
|
|
206
208
|
}),
|
|
207
209
|
"shop",
|
|
@@ -241,7 +243,7 @@ class ShopController extends Controller {
|
|
|
241
243
|
return this.render(html);
|
|
242
244
|
}
|
|
243
245
|
|
|
244
|
-
/** L'API que l'interface appellera —
|
|
246
|
+
/** L'API que l'interface appellera — sur l'origine de la page, sans proxy. */
|
|
245
247
|
@Get("/api/products")
|
|
246
248
|
products() {
|
|
247
249
|
return this.renderJson([{ id: "1", label: "Cordage 12mm" }]);
|
|
@@ -268,9 +270,6 @@ class Shop extends Module {
|
|
|
268
270
|
frontend.registerEntry(this, {
|
|
269
271
|
type: "react19",
|
|
270
272
|
entry: "./frontend/src/main.tsx",
|
|
271
|
-
// SANS cette ligne, fetch("/shop/api/products") depuis la page servie par
|
|
272
|
-
// Vite reçoit le repli SPA (du HTML) → « Unexpected token '<' ».
|
|
273
|
-
apiProxyPaths: ["/shop/api"],
|
|
274
273
|
});
|
|
275
274
|
return this;
|
|
276
275
|
}
|
|
@@ -302,7 +301,7 @@ d'entrée. Ton `index.html` est **le tien** : mets-y tes polices, tes méta, tes
|
|
|
302
301
|
|
|
303
302
|
Le marqueur `<!--nodefony:frontend-->` indique **où** injecter les balises ; sans lui, elles sont
|
|
304
303
|
posées avant `</head>`. Le `<script>` d'entrée que tu vois en bas est retiré automatiquement au rendu
|
|
305
|
-
(`TemplateHelper.injectIntoHtml()`, `TemplateHelper.ts:
|
|
304
|
+
(`TemplateHelper.injectIntoHtml()`, `TemplateHelper.ts:152`) : il n'est résolvable que par Vite quand
|
|
306
305
|
Vite sert lui-même la page, ce qui n'est pas le cas ici.
|
|
307
306
|
|
|
308
307
|
### Ce qu'on observe
|
|
@@ -312,16 +311,20 @@ Vite sert lui-même la page, ce qui n'est pas le cas ici.
|
|
|
312
311
|
# INFO registered entry: shop (react19) from "shop"
|
|
313
312
|
# INFO vite [default] ready on 127.0.0.1:5173
|
|
314
313
|
|
|
315
|
-
# La page vient de Nodefony
|
|
316
|
-
curl -
|
|
317
|
-
# src="
|
|
318
|
-
# src="
|
|
314
|
+
# La page vient de Nodefony ; ses balises sont RELATIVES, sous /_vite/<famille>/
|
|
315
|
+
curl -sk https://localhost:5152/shop | grep -o 'src="[^"]*"'
|
|
316
|
+
# src="/_vite/default/@vite/client"
|
|
317
|
+
# src="/_vite/default/@fs/…/shop/frontend/src/main.tsx"
|
|
319
318
|
|
|
320
|
-
#
|
|
321
|
-
curl -
|
|
319
|
+
# Le module est relayé par Nodefony : même origine que la page
|
|
320
|
+
curl -sk -o /dev/null -w '%{http_code}\n' https://localhost:5152/_vite/default/@vite/client
|
|
321
|
+
# 200
|
|
322
|
+
|
|
323
|
+
# L'API répond en JSON — le navigateur l'appelle sur la même origine
|
|
324
|
+
curl -sk https://localhost:5152/shop/api/products
|
|
322
325
|
# [{"id":"1","label":"Cordage 12mm"}]
|
|
323
326
|
|
|
324
|
-
# L'état du superviseur, en une commande
|
|
327
|
+
# L'état du superviseur, en une commande — l'endpoint est INTERNE (boucle locale)
|
|
325
328
|
npx nodefony frontend:status
|
|
326
329
|
# state : ready
|
|
327
330
|
# endpoint : 127.0.0.1:5173
|
|
@@ -350,28 +353,17 @@ JSON Schema pour l'écran de configuration de Studio.
|
|
|
350
353
|
|
|
351
354
|
| Option | Type | Défaut | Effet |
|
|
352
355
|
| ------------------------ | ------------------ | ------------- | --------------------------------------------------------------------------------- |
|
|
353
|
-
| `devHost` | `string` | `"127.0.0.1"` |
|
|
354
|
-
| `devPort` | `number` | `5173` | Port de base. Occupé ⇒ le superviseur essaie les suivants.
|
|
356
|
+
| `devHost` | `string` | `"127.0.0.1"` | Adresse d'écoute de Vite. Laisser la boucle locale : Nodefony le relaie. |
|
|
357
|
+
| `devPort` | `number` | `5173` | Port de base, interne. Occupé ⇒ le superviseur essaie les suivants. |
|
|
355
358
|
| `autoStartInDevelopment` | `boolean` | `true` | Démarrer Vite au boot en `development`. Ignoré ailleurs. |
|
|
356
359
|
| `startupTimeoutMs` | `number` | `30000` | Attente du `Local: …` de Vite avant de déclarer l'échec. |
|
|
357
360
|
| `pipeViteLogs` | `boolean` | `true` | Reverser la sortie de Vite dans le journal Nodefony. |
|
|
358
|
-
| `https` | `boolean` | `false` | Servir Vite en HTTPS avec **les certificats de Nodefony** (pas de doublon). |
|
|
359
361
|
| `viteEnv` | `Record<string,…>` | `{}` | Variables passées au processus Vite ; les clés `VITE_*` atteignent le navigateur. |
|
|
360
362
|
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
| `backendHost` | `string` | `"127.0.0.1"` | Hôte visé par le proxy de Vite. |
|
|
366
|
-
| `backendPort` | `number` | `5151` | Port visé — **une intention**, voir l'encadré ci-dessous. |
|
|
367
|
-
| `backendProtocol` | `"http" \| "https"` | `"http"` | Protocole du proxy. `https` pour viser le serveur TLS. |
|
|
368
|
-
|
|
369
|
-
> [!IMPORTANT]
|
|
370
|
-
> **`backendPort` n'est pas forcément le port écouté.** Avec une politique de port automatique, un
|
|
371
|
-
> 5151 occupé fait glisser l'écoute sur 5153. Un proxy figé enverrait alors les appels de ton
|
|
372
|
-
> interface vers le serveur d'une **autre** application. Le module lit donc le port réel sur le
|
|
373
|
-
> serveur lui-même (`FrontendService.resolveBackendPort()`, `FrontendService.ts:493`) et journalise
|
|
374
|
-
> l'écart.
|
|
363
|
+
> [!NOTE]
|
|
364
|
+
> **`https` et `publicOrigin` n'existent plus.** Elles réglaient l'origine par laquelle le
|
|
365
|
+
> navigateur joignait Vite ; il ne le joint plus — l'origine et le chiffrement sont ceux de la page.
|
|
366
|
+
> Une configuration qui les déclare encore interrompt le démarrage en les nommant : retire-les.
|
|
375
367
|
|
|
376
368
|
### Le build de production
|
|
377
369
|
|
|
@@ -401,6 +393,45 @@ s'appliquent même si tu omets la section entière.
|
|
|
401
393
|
> **En intégration continue, mets `autoRestart: false`.** Un Vite qui plante puis se relance en
|
|
402
394
|
> boucle fait passer ton pipeline au vert avec une interface morte. Sans relance, l'échec est visible.
|
|
403
395
|
|
|
396
|
+
## 📱 Hors de la boucle locale — téléphone, conteneur, réseau
|
|
397
|
+
|
|
398
|
+
Beaucoup d'API du navigateur exigent une page **sécurisée** dès qu'on quitte `localhost` : caméra et
|
|
399
|
+
micro (`getUserMedia`), Service Workers, `crypto.subtle`, presse-papiers, WebAuthn. Comme page,
|
|
400
|
+
modules et socket partagent une seule origine HTTPS, il suffit que **cette** origine soit joignable —
|
|
401
|
+
le reste suit, sans réglage côté Vite.
|
|
402
|
+
|
|
403
|
+
**Depuis un téléphone ou un autre poste du réseau local.** En développement, l'application n'écoute
|
|
404
|
+
que la boucle locale : un autre appareil reçoit une connexion refusée. Dans une application générée
|
|
405
|
+
par `nodefony create app`, l'interrupteur `NF_BIND_ALL` l'ouvre à toutes les interfaces :
|
|
406
|
+
|
|
407
|
+
```bash
|
|
408
|
+
# .env (ou en préfixe de la commande)
|
|
409
|
+
NF_BIND_ALL=true
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
Ouvre ensuite `https://<IP-de-ta-machine>:5152/` sur l'appareil, et accepte **une** fois le
|
|
413
|
+
certificat de développement : page, modules et rechargement à chaud passent par lui. Vite, lui,
|
|
414
|
+
reste sur `127.0.0.1` — seul Nodefony est exposé.
|
|
415
|
+
|
|
416
|
+
> [!WARNING]
|
|
417
|
+
> Le serveur de développement expose ses outils d'administration. N'ouvre `NF_BIND_ALL` que sur un
|
|
418
|
+
> réseau de confiance ; il est désactivé par défaut pour cette raison. En production, l'écoute est
|
|
419
|
+
> déjà sur toutes les interfaces et l'interrupteur ne change rien.
|
|
420
|
+
|
|
421
|
+
**Depuis un navigateur en conteneur.** Le conteneur joint la machine par `host.docker.internal`, que
|
|
422
|
+
le gabarit d'application accepte déjà en développement.
|
|
423
|
+
|
|
424
|
+
**Si `domainCheck` est actif**, la barrière d'hôte refuse tout nom absent de `trustedHosts` (réponse
|
|
425
|
+
`421`), relais `/_vite/` compris : ajoute l'IP ou le nom de l'appareil à `trustedHosts` du module
|
|
426
|
+
HTTP. Sans `domainCheck` — le défaut d'une application générée — tout `Host` passe.
|
|
427
|
+
|
|
428
|
+
Deux limites viennent des appareils, pas du relais :
|
|
429
|
+
|
|
430
|
+
- le client cible **ES2022** ; un appareil plus ancien affiche une page blanche — voir
|
|
431
|
+
[la cible du client](../../../../../docs/guides/compatibilite.md#navigateurs--la-cible-du-client) ;
|
|
432
|
+
- un appareil qui n'applique pas son exception de certificat aux WebSocket (vu sur une TV) charge la
|
|
433
|
+
page mais pas le rechargement à chaud. En `http://<IP>:5151/`, il passe — sans contexte sécurisé.
|
|
434
|
+
|
|
404
435
|
## 🔌 Les deux modes de livraison de l'interface
|
|
405
436
|
|
|
406
437
|
C'est la section à lire avant tout déploiement, et **avant de publier un module** sur npm. La
|
|
@@ -473,16 +504,17 @@ sequenceDiagram
|
|
|
473
504
|
S->>S: regroupe les entrées par famille + plan de ports
|
|
474
505
|
S->>V: écrit vite.config.generated.mjs, puis spawn
|
|
475
506
|
V-->>S: « Local: http://host:port » ⇒ état ready
|
|
476
|
-
S->>S:
|
|
507
|
+
S->>S: monte /_vite/<famille>/ sur le proxy inverse
|
|
508
|
+
S->>S: déclare ses besoins CSP au pare-feu (sans origine)
|
|
477
509
|
Note over S,V: sonde de vie périodique · relance sur plantage
|
|
478
510
|
K->>S: onTerminate
|
|
479
511
|
S->>V: SIGINT, puis SIGKILL au bout de 3 s
|
|
480
512
|
```
|
|
481
513
|
|
|
482
|
-
**Pourquoi `onServersReady` et pas `onReady`.** Vite
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
514
|
+
**Pourquoi `onServersReady` et pas `onReady`.** Vite démarre une fois les serveurs Nodefony en
|
|
515
|
+
écoute (`FrontendService.init()`, `FrontendService.ts:142`) : rien ne peut lui être relayé avant, le relais `/_vite/` vivant dans leur
|
|
516
|
+
pipeline, et le lancer ensuite ne retarde pas l'ouverture des ports — Vite compile pendant que
|
|
517
|
+
Nodefony sert déjà.
|
|
486
518
|
|
|
487
519
|
### Les pièces
|
|
488
520
|
|
|
@@ -490,7 +522,7 @@ intermittent, apparaissant seulement quand le navigateur est plus rapide que le
|
|
|
490
522
|
| ----------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------- |
|
|
491
523
|
| `FrontendService` | l'orchestrateur : entrées, familles, cycle de vie, rendu | `FrontendService.ts:70` |
|
|
492
524
|
| `ViteProcessSupervisor` | lance, surveille, relance et arrête **un** processus Vite | `ViteProcessSupervisor.ts:236` |
|
|
493
|
-
| `ViteConfigGenerator` | écrit la configuration Vite (fonction pure, testée seule) | `ViteConfigGenerator.toMjs()` (`ViteConfigGenerator.ts:
|
|
525
|
+
| `ViteConfigGenerator` | écrit la configuration Vite (fonction pure, testée seule) | `ViteConfigGenerator.toMjs()` (`ViteConfigGenerator.ts:63`) |
|
|
494
526
|
| `ViteBuilder` | construit l'objet de configuration Vite pour le build en processus | `ViteBuilder.buildViteConfig()` (`ViteBuilder.ts:95`) |
|
|
495
527
|
| `TemplateHelper` | produit les balises (dev) ou lit le manifeste (prod) | `TemplateHelper.ts:36` |
|
|
496
528
|
| `isolationGroups` | à quelle famille appartient un preset, et sur quel bloc de ports | `isolationGroup()` (`isolationGroups.ts:39`) |
|
|
@@ -506,42 +538,38 @@ il importe lui-même les greffons dont les presets détectés ont besoin.
|
|
|
506
538
|
**Ne l'édite jamais** : il est réécrit à chaque démarrage. Ce qu'il contient de notable :
|
|
507
539
|
|
|
508
540
|
- une **entrée par bundle** (`input`), d'où le multi-modules dans une seule instance ;
|
|
509
|
-
- la `base`
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
541
|
+
- la `base` sur le **chemin réservé de la famille** (`/_vite/<famille>/`, `devBasePath()`,
|
|
542
|
+
`isolationGroups.ts:75`) — chaque URL que Vite écrit dans un module retombe ainsi sous le préfixe
|
|
543
|
+
que Nodefony relaie, sur l'origine de la page ;
|
|
544
|
+
- `strictPort` : c'est le superviseur qui choisit le port, et le relais vise ce port. Un Vite qui
|
|
545
|
+
glisserait de lui-même servirait ailleurs que là où le relais l'attend ;
|
|
546
|
+
- **ni `allowedHosts` ni `cors`** : le relais réécrit `Host` en `127.0.0.1:<port>`, que Vite accepte
|
|
547
|
+
d'office, et aucune requête n'est inter-origines — les deux barrières de Vite restent à leur
|
|
548
|
+
réglage le plus strict ;
|
|
513
549
|
- un `server.fs.allow` élargi aux racines de **chaque** entrée — sans quoi deux modules ayant tous
|
|
514
550
|
deux `frontend/src/main.tsx` verraient le second recevoir le fichier du premier ;
|
|
515
551
|
- un `resolve.dedupe` sur les paquets du framework UI — deux copies de React dans la même page
|
|
516
552
|
produisent l'énigmatique « Invalid hook call » et une page blanche.
|
|
517
553
|
|
|
518
|
-
###
|
|
519
|
-
|
|
520
|
-
C'est le mécanisme le plus important à comprendre du module, parce que son absence produit une erreur
|
|
521
|
-
qui ne parle pas de proxy.
|
|
554
|
+
### Le relais — une origine pour tout
|
|
522
555
|
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
556
|
+
Au démarrage de chaque famille, le service monte son chemin réservé sur le
|
|
557
|
+
[proxy inverse](../../http/docs/reverse-proxy.md) de `@nodefony/http`
|
|
558
|
+
(`FrontendService.mountDevProxy()`, `FrontendService.ts:486`). Toute requête sous `/_vite/<famille>/`
|
|
559
|
+
— module, style, image importée, et l'upgrade WebSocket du rechargement à chaud — est alors relayée
|
|
560
|
+
à Vite, sur la boucle locale ; la cible est le port **que Vite sert vraiment**
|
|
561
|
+
(`TemplateHelper.devTarget()`, `TemplateHelper.ts:91`), jamais un port seulement retenu par une
|
|
562
|
+
instance tombée, qu'une autre application aurait pu reprendre.
|
|
526
563
|
|
|
527
|
-
|
|
528
|
-
SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
|
|
529
|
-
```
|
|
530
|
-
|
|
531
|
-
Déclarer `apiProxyPaths: ["/shop/api"]` inscrit ce préfixe dans le proxy de la configuration générée :
|
|
532
|
-
Vite transmet alors ces requêtes à Nodefony, sur le port **réellement** écouté. Trois points à
|
|
533
|
-
connaître :
|
|
564
|
+
Ce que ça change pour toi :
|
|
534
565
|
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
> [!WARNING]
|
|
543
|
-
> Ne proxifie **que** tes chemins d'API. Proxifier `/` renverrait aussi les modules et le rechargement
|
|
544
|
-
> à chaud vers Nodefony, qui n'en sait rien : plus rien ne se charge.
|
|
566
|
+
- **une seule origine** — la page, ses scripts et son socket partagent l'hôte et le port de la page.
|
|
567
|
+
Aucun contenu mixte, aucun CORS, et **un seul certificat** à accepter ;
|
|
568
|
+
- **aucune adresse à configurer** — le client Vite déduit l'adresse de son socket de l'URL qui l'a
|
|
569
|
+
chargé, donc de celle que le navigateur a tapée : `localhost`, l'IP du réseau local ou
|
|
570
|
+
`host.docker.internal` fonctionnent sans réglage ;
|
|
571
|
+
- **le relais est réservé au développement** — en production, rien n'est monté : `/_vite/…`
|
|
572
|
+
répond 404.
|
|
545
573
|
|
|
546
574
|
### Familles d'isolation — pourquoi Angular a son Vite
|
|
547
575
|
|
|
@@ -555,13 +583,13 @@ extensions différentes n'y changent rien, et l'option `exclude` du greffon Reac
|
|
|
555
583
|
|
|
556
584
|
D'où le regroupement par **famille** (`isolationGroup()`, `isolationGroups.ts:39`) : `angular` et
|
|
557
585
|
`vue` ont chacune la leur, tout le reste partage `default`. Chaque famille obtient un **bloc de ports disjoint**
|
|
558
|
-
(`familyPortPlan()`, `isolationGroups.ts:
|
|
586
|
+
(`familyPortPlan()`, `isolationGroups.ts:112`) de taille `portRetryAttempts + 1` : ainsi, une instance
|
|
559
587
|
qui glisse de port sur conflit ne peut jamais empiéter sur le bloc d'une autre. La famille principale
|
|
560
|
-
garde le port habituel (`PRIMARY_FAMILY`, `isolationGroups.ts:
|
|
588
|
+
garde le port habituel (`PRIMARY_FAMILY`, `isolationGroups.ts:84`).
|
|
561
589
|
|
|
562
590
|
**Les familles démarrent indépendamment.** Si Angular échoue, React continue de fonctionner : le
|
|
563
591
|
démarrage n'échoue que si **aucune** famille n'a pu démarrer (`FrontendService.startDev()`,
|
|
564
|
-
`FrontendService.ts:
|
|
592
|
+
`FrontendService.ts:314`).
|
|
565
593
|
|
|
566
594
|
### Résilience — ce qui se passe quand Vite tombe
|
|
567
595
|
|
|
@@ -571,11 +599,11 @@ les processus meurent.
|
|
|
571
599
|
| Situation | Réponse |
|
|
572
600
|
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
573
601
|
| Port occupé au lancement | essai sur le port suivant, jusqu'à `portRetryAttempts` (`ViteProcessSupervisor.ts:301`) |
|
|
574
|
-
| Vite plante | relance avec délai exponentiel plafonné (`scheduleRestart()`, `ViteProcessSupervisor.ts:
|
|
602
|
+
| Vite plante | relance avec délai exponentiel plafonné (`scheduleRestart()`, `ViteProcessSupervisor.ts:704`) |
|
|
575
603
|
| Vite ne répond plus (gelé) | sonde périodique ; après N échecs, Vite est tué pour être relancé (`ViteProcessSupervisor.ts:787`) |
|
|
576
604
|
| Deux `start()` concurrents | la promesse en cours est partagée — jamais deux processus |
|
|
577
|
-
| Ctrl+C au terminal | le signal marque un arrêt **voulu** : pas de relance (`markShutdown`, `ViteProcessSupervisor.ts:
|
|
578
|
-
| Arrêt du kernel | `SIGINT`, puis `SIGKILL` après 3 s — aucun zombie ne bloque le port (`ViteProcessSupervisor.ts:
|
|
605
|
+
| Ctrl+C au terminal | le signal marque un arrêt **voulu** : pas de relance (`markShutdown`, `ViteProcessSupervisor.ts:272`) |
|
|
606
|
+
| Arrêt du kernel | `SIGINT`, puis `SIGKILL` après 3 s — aucun zombie ne bloque le port (`ViteProcessSupervisor.ts:888`) |
|
|
579
607
|
|
|
580
608
|
Deux subtilités valent d'être connues, parce qu'elles expliquent des comportements sinon
|
|
581
609
|
incompréhensibles :
|
|
@@ -593,7 +621,7 @@ incompréhensibles :
|
|
|
593
621
|
repayant l'attente de démarrage à chaque essai.
|
|
594
622
|
|
|
595
623
|
Les écouteurs attachés au processus enfant sont suivis puis retirés à chaque mort
|
|
596
|
-
(`cleanupChildListeners()`, `ViteProcessSupervisor.ts:
|
|
624
|
+
(`cleanupChildListeners()`, `ViteProcessSupervisor.ts:959`) : sans cela, les relances successives les
|
|
597
625
|
accumuleraient jusqu'à l'avertissement de fuite.
|
|
598
626
|
|
|
599
627
|
## 🧰 API publique
|
|
@@ -604,26 +632,24 @@ et dans les types du paquet — jamais recopiées ici, où elles se périmeraien
|
|
|
604
632
|
|
|
605
633
|
### `registerEntry` — la déclaration d'une interface
|
|
606
634
|
|
|
607
|
-
`FrontendService.registerEntry()` (`FrontendService.ts:
|
|
635
|
+
`FrontendService.registerEntry()` (`FrontendService.ts:228`) est appelée par le module consommateur,
|
|
608
636
|
dans son `onKernelBoot()`. Elle résout les chemins relatifs, calcule le préfixe public et renvoie
|
|
609
|
-
l'entrée résolue (`IResolvedFrontendEntry`, `IFrontBuilder.ts:
|
|
610
|
-
|
|
611
|
-
| Champ
|
|
612
|
-
|
|
|
613
|
-
| `type`
|
|
614
|
-
| `entry`
|
|
615
|
-
| `root`
|
|
616
|
-
| `outDir`
|
|
617
|
-
| `name`
|
|
618
|
-
| `publicPath`
|
|
619
|
-
| `apiProxyPaths` | non | `[]` | Les préfixes que Vite doit transmettre à Nodefony. |
|
|
637
|
+
l'entrée résolue (`IResolvedFrontendEntry`, `IFrontBuilder.ts:33`).
|
|
638
|
+
|
|
639
|
+
| Champ | Requis | Défaut | Rôle |
|
|
640
|
+
| ------------ | ------ | ------------------ | --------------------------------------------------------------- |
|
|
641
|
+
| `type` | oui | — | Le preset : `react19`, `vue3`, `angular`, `svelte5`, `vanilla`. |
|
|
642
|
+
| `entry` | oui | — | Le fichier d'entrée, relatif à la racine du module. |
|
|
643
|
+
| `root` | non | `./frontend` | La racine front (celle qui contient `index.html`). |
|
|
644
|
+
| `outDir` | non | `./public/dist` | Où le build écrit ce bundle. |
|
|
645
|
+
| `name` | non | nom du module | Nom logique du bundle — c'est la clé de `renderTags(...)`. |
|
|
646
|
+
| `publicPath` | non | `/_assets/<name>/` | Préfixe d'URL des assets en production. |
|
|
620
647
|
|
|
621
648
|
```ts ignore
|
|
622
649
|
frontend.registerEntry(this, {
|
|
623
650
|
type: "vue3",
|
|
624
651
|
entry: "./frontend/src/main.ts",
|
|
625
652
|
name: "admin", // → renderTags("admin"), assets sous /_assets/admin/
|
|
626
|
-
apiProxyPaths: ["/admin/api"],
|
|
627
653
|
});
|
|
628
654
|
```
|
|
629
655
|
|
|
@@ -644,12 +670,12 @@ const tags = frontend.renderTags("shop", context.cspNonce);
|
|
|
644
670
|
const html = frontend.renderDocument("shop", context.cspNonce);
|
|
645
671
|
```
|
|
646
672
|
|
|
647
|
-
`renderDocument` (`FrontendService.ts:
|
|
673
|
+
`renderDocument` (`FrontendService.ts:753`) lit l'`index.html` **de ton module**, retire le `<script>`
|
|
648
674
|
d'entrée source, injecte les balises au marqueur (ou avant `</head>`), et renvoie le document.
|
|
649
675
|
Pas d'`index.html` ? Une coquille minimale est générée. En production, l'index est mis en cache ; en
|
|
650
676
|
développement il est relu à chaque appel, pour que tes modifications de la coquille apparaissent.
|
|
651
677
|
|
|
652
|
-
Ce qui est injecté en développement (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts:
|
|
678
|
+
Ce qui est injecté en développement (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts:200`) :
|
|
653
679
|
|
|
654
680
|
1. le **préambule React Fast Refresh** pour les entrées `react19` — sans lui, `@vitejs/plugin-react`
|
|
655
681
|
refuse de démarrer ;
|
|
@@ -657,9 +683,9 @@ Ce qui est injecté en développement (`TemplateHelper.renderDevTags()`, `Templa
|
|
|
657
683
|
3. ton entrée, servie par son **chemin absolu** (`/@fs/…`) plutôt que relatif — c'est ce qui permet à
|
|
658
684
|
deux modules d'avoir chacun leur `frontend/src/main.tsx` sans collision ;
|
|
659
685
|
4. un pont qui relaie les événements de rechargement vers la barre de débogage, **sans ouvrir de
|
|
660
|
-
seconde connexion** (`hmrBridgeTag()`, `TemplateHelper.ts:
|
|
686
|
+
seconde connexion** (`hmrBridgeTag()`, `TemplateHelper.ts:277`) ;
|
|
661
687
|
5. la barre de débogage elle-même, résolue une fois et servie via Vite (`debugBarTag()`,
|
|
662
|
-
`TemplateHelper.ts:
|
|
688
|
+
`TemplateHelper.ts:303`).
|
|
663
689
|
|
|
664
690
|
Quand Vite n'est pas prêt, le rendu ne lève **jamais** : il renvoie un commentaire HTML disant
|
|
665
691
|
l'état. Une page dégradée reste une page.
|
|
@@ -667,7 +693,7 @@ l'état. Une page dégradée reste une page.
|
|
|
667
693
|
### Les helpers de vue
|
|
668
694
|
|
|
669
695
|
Si tu rends une vue Eta plutôt qu'une chaîne, trois helpers sont déjà dans tes variables locales
|
|
670
|
-
(`Controller.withFrontendLocals()`, `Controller.ts:
|
|
696
|
+
(`Controller.withFrontendLocals()`, `Controller.ts:594`) — inspirés des helpers d'assets de Symfony :
|
|
671
697
|
|
|
672
698
|
```html
|
|
673
699
|
<%~ frontendDocument("shop") %>
|
|
@@ -692,21 +718,21 @@ Dans une application générée par `nodefony create app`, tu n'as pas à y pens
|
|
|
692
718
|
**`npm run build` construit l'application entière** — le backend (rolldown) puis le front (il
|
|
693
719
|
chaîne `nodefony frontend:build`). Un seul geste avant `npm start` ou dans un pipeline.
|
|
694
720
|
|
|
695
|
-
`FrontendService.build()` (`FrontendService.ts:
|
|
721
|
+
`FrontendService.build()` (`FrontendService.ts:634`) appelle Vite **entrée par entrée**, et non une
|
|
696
722
|
fois pour toutes. Ce n'est pas un détail : chaque bundle a sa racine, son dossier de sortie, sa base
|
|
697
723
|
et son manifeste — c'est ce qui rend le multi-modules possible et ce qui isole Angular.
|
|
698
724
|
|
|
699
725
|
Quatre comportements à connaître :
|
|
700
726
|
|
|
701
727
|
- **Idempotent.** Une entrée dont le manifeste est plus récent que ses sources est ignorée
|
|
702
|
-
(`isBuildFresh()`, `FrontendService.ts:
|
|
728
|
+
(`isBuildFresh()`, `FrontendService.ts:704`) — le scan est borné au dossier front et saute
|
|
703
729
|
`node_modules`. Relancer un déploiement ne recompile pas tout.
|
|
704
730
|
- **Les échecs sont collectés, pas propagés.** Un bundle en échec n'arrête pas les autres ; la
|
|
705
731
|
commande passe le code de sortie à `1` s'il en reste un — de quoi casser un pipeline sans masquer
|
|
706
732
|
les autres résultats.
|
|
707
733
|
- **Le résultat est un bilan** : construits / ignorés / en échec, journalisé et renvoyé.
|
|
708
734
|
- **Un démarrage en production sans build se répare — ou se dénonce.** `setupProd()`
|
|
709
|
-
(`FrontendService.ts:
|
|
735
|
+
(`FrontendService.ts:525`) vérifie le manifeste de chaque entrée AVANT de monter les statics.
|
|
710
736
|
Manifeste absent et Vite installé (poste de développement, devDependencies présentes) : le build
|
|
711
737
|
tourne **une fois au démarrage**, annoncé en WARNING — fini l'écran blanc après un
|
|
712
738
|
`nodefony production --detach` lancé trop tôt. Manifeste absent et Vite introuvable (image de
|
|
@@ -730,7 +756,7 @@ page. Les trois restent alignés par construction — impossible d'en changer un
|
|
|
730
756
|
deux autres.
|
|
731
757
|
|
|
732
758
|
Défaut : `/_assets/<name>/`, normalisé avec ses barres obliques
|
|
733
|
-
(`normalizePublicPath()`, `FrontendService.ts:
|
|
759
|
+
(`normalizePublicPath()`, `FrontendService.ts:70`). Chaque bundle a donc son espace, sans collision
|
|
734
760
|
entre modules.
|
|
735
761
|
|
|
736
762
|
`assetBaseUrl` ajoute une couche : la base d'un CDN. Renseignée, elle préfixe la `base` du build et
|
|
@@ -742,18 +768,18 @@ use("@nodefony/frontend", { assetBaseUrl: "https://cdn.example.com" });
|
|
|
742
768
|
// → <script src="https://cdn.example.com/_assets/shop/main-a1b2c3.js">
|
|
743
769
|
```
|
|
744
770
|
|
|
745
|
-
En production, `setupProd()` (`FrontendService.ts:
|
|
771
|
+
En production, `setupProd()` (`FrontendService.ts:525`) monte chaque dossier de sortie sur son
|
|
746
772
|
`publicPath` via le serveur statique — résolu **par nom**, jamais par import, pour ne pas créer de
|
|
747
773
|
cycle. Si ce service est absent (proxy frontal, CDN devant), un avertissement le dit et rien n'est
|
|
748
774
|
monté : c'est un déploiement valide, pas une panne.
|
|
749
775
|
|
|
750
776
|
### Ce qui est servi en production
|
|
751
777
|
|
|
752
|
-
`renderProdTags()` (`TemplateHelper.ts:
|
|
778
|
+
`renderProdTags()` (`TemplateHelper.ts:336`) lit `manifest.json` — la carte produite par Vite — et
|
|
753
779
|
émet, dans cet ordre : les feuilles de style d'abord (pour éviter le flash de contenu non stylé), les
|
|
754
780
|
préchargements des morceaux partagés, puis le script d'entrée. Le manifeste est lu **une fois par
|
|
755
781
|
dossier de sortie** et mis en cache : aucune lecture disque par requête. Le CSS est collecté
|
|
756
|
-
récursivement à travers les imports (`collectCss()`, `TemplateHelper.ts:
|
|
782
|
+
récursivement à travers les imports (`collectCss()`, `TemplateHelper.ts:410`), sans quoi le style
|
|
757
783
|
d'un morceau partagé manquerait sur certaines pages.
|
|
758
784
|
|
|
759
785
|
Manifeste absent ? Un commentaire HTML le dit, avec la commande à lancer. Pas d'exception, pas de
|
|
@@ -773,7 +799,7 @@ Deux points d'attention avant de se lancer :
|
|
|
773
799
|
|
|
774
800
|
- le preset alimente le build en processus (`ViteBuilder`), mais la configuration du **serveur de
|
|
775
801
|
développement** est écrite par le générateur, qui possède sa propre correspondance type → greffon
|
|
776
|
-
(`ViteConfigGenerator.toMjs()`, `ViteConfigGenerator.ts:
|
|
802
|
+
(`ViteConfigGenerator.toMjs()`, `ViteConfigGenerator.ts:63`). Un nouveau type doit être ajouté aux
|
|
777
803
|
**deux** endroits, sinon il lève `FrontendPresetUnknownError` (`FrontendError.ts:19`) ;
|
|
778
804
|
- si le nouveau framework transforme des fichiers qui ne lui appartiennent pas, il lui faut sa propre
|
|
779
805
|
famille d'isolation — c'est la leçon d'Angular.
|
|
@@ -785,15 +811,16 @@ toute autre stratégie.
|
|
|
785
811
|
## 🔐 Sécurité — la CSP, sans trou et sans bricolage
|
|
786
812
|
|
|
787
813
|
Une politique de sécurité du contenu stricte bloque, par construction, les scripts venus d'une autre
|
|
788
|
-
origine.
|
|
789
|
-
**
|
|
814
|
+
origine. Grâce au relais, il n'y en a pas : en développement comme en production, modules, styles et
|
|
815
|
+
socket viennent de l'origine de la page. La politique n'a donc **aucune origine à autoriser** —
|
|
816
|
+
`'self'` suffit.
|
|
790
817
|
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
(`#registerCsp()`, `FrontendService.ts:
|
|
794
|
-
nonce par requête. À l'arrêt,
|
|
818
|
+
Le développement a pourtant deux besoins que la politique stricte refuse. Plutôt que de l'affaiblir,
|
|
819
|
+
le service les **compose** : une fois Vite prêt, il déclare son fragment au pare-feu
|
|
820
|
+
(`#registerCsp()`, `FrontendService.ts:782`), qui émet **un seul** en-tête, fragment fusionné et
|
|
821
|
+
nonce par requête. À l'arrêt, le fragment est retiré et la politique redevient stricte.
|
|
795
822
|
|
|
796
|
-
Le fragment
|
|
823
|
+
Le fragment (`#viteCspFragment()`, `FrontendService.ts:804`) mérite deux explications, parce
|
|
797
824
|
qu'elles piègent tout le monde :
|
|
798
825
|
|
|
799
826
|
- **`'self'` est répété dans chaque directive.** `connect-src`, `style-src`, `img-src` et `font-src`
|
|
@@ -803,9 +830,8 @@ qu'elles piègent tout le monde :
|
|
|
803
830
|
pas. En revanche `'unsafe-inline'` n'est **pas** accordé aux scripts : le préambule injecté porte un
|
|
804
831
|
nonce.
|
|
805
832
|
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
accéder à ton application par un hôte virtuel bloquerait tout.
|
|
833
|
+
Aucune origine n'y figure : le fragment est le même quel que soit le nom par lequel on ouvre la page
|
|
834
|
+
— `localhost`, une IP du réseau local, un nom de conteneur.
|
|
809
835
|
|
|
810
836
|
> [!IMPORTANT]
|
|
811
837
|
> **Ce fragment n'existe qu'en développement.** En production le superviseur ne démarre pas, donc rien
|
|
@@ -829,7 +855,7 @@ Sur le chemin chaud du rendu, trois précautions :
|
|
|
829
855
|
- le **manifeste** est lu une fois par dossier de sortie, jamais par requête ;
|
|
830
856
|
- l'**`index.html`** est mis en cache en production (relu en développement, où la fraîcheur prime) ;
|
|
831
857
|
- les **écouteurs** du processus enfant sont suivis et retirés à chaque mort
|
|
832
|
-
(`trackListener()`, `ViteProcessSupervisor.ts:
|
|
858
|
+
(`trackListener()`, `ViteProcessSupervisor.ts:949`) — sans quoi les relances les accumuleraient.
|
|
833
859
|
|
|
834
860
|
La sonde de vie coûte une requête HTTP toutes les trente secondes par famille. Elle est désactivable
|
|
835
861
|
(`healthCheckIntervalMs: 0`) si ce budget te gêne, au prix de la détection d'un Vite gelé.
|
|
@@ -861,19 +887,21 @@ apparaisse avant le « prêt ».
|
|
|
861
887
|
<!-- prettier-ignore -->
|
|
862
888
|
| Symptôme | Cause | Correction |
|
|
863
889
|
| --- | --- | --- |
|
|
864
|
-
| `Unexpected token '<'` sur un `fetch` | Vite répond son repli SPA
|
|
890
|
+
| `Unexpected token '<'` sur un `fetch` | la page est ouverte sur le port de Vite, qui répond son repli SPA | ouvrir la page par Nodefony — c'est elle qui appelle l'API sur sa propre origine |
|
|
865
891
|
| Le service `frontend` est introuvable au `onKernelBoot` | ordre de chargement des modules | placer `@nodefony/frontend` **avant** ses consommateurs dans `modules` |
|
|
866
892
|
| L'entrée n'apparaît pas dans le superviseur | `registerEntry` appelé après `onKernelReady` | enregistrer dans `onKernelBoot`, jamais plus tard |
|
|
867
893
|
| `@vitejs/plugin-react can't detect preamble` | le préambule React n'est pas dans la page | rendre via `renderTags`/`renderDocument`, qui l'injectent |
|
|
868
894
|
| Page blanche + « Invalid hook call » | deux copies de React dans la page (deux `node_modules`) | comportement couvert par `resolve.dedupe` ; purger le pré-empaquetage de Vite |
|
|
869
895
|
| Deux modules affichent la **même** interface | racines identiques et URL relatives | comportement couvert : l'entrée est servie par chemin absolu `/@fs/…` |
|
|
870
896
|
| Vite écoute sur un autre port que `devPort` | port occupé ⇒ reprise sur le suivant | lire le port **réel** dans `frontend:status`, jamais la configuration |
|
|
871
|
-
| Les appels d'API partent vers une autre application | port du serveur glissé, proxy figé sur `backendPort` | comportement couvert : le port réel est lu sur le serveur ; vérifier le journal |
|
|
872
897
|
| `no frontend entries declared` au démarrage | aucun module n'a appelé `registerEntry` | normal si tu n'as pas d'interface ; sinon voir les deux lignes ci-dessus |
|
|
873
898
|
| `max restarts reached` | Vite plante en boucle | lire les lignes `[vite]` du journal — l'erreur est dans ton code front |
|
|
874
|
-
| Le navigateur
|
|
875
|
-
|
|
|
876
|
-
|
|
|
899
|
+
| Le navigateur alerte sur le certificat | certificat de développement auto-signé, sans autorité installée sur l'appareil | l'accepter **une** fois — page, modules et socket partagent ce certificat ; ou installer l'autorité racine de développement |
|
|
900
|
+
| Connexion refusée depuis un téléphone | en développement, l'application n'écoute que la boucle locale | `NF_BIND_ALL=true` — voir [Hors de la boucle locale](#-hors-de-la-boucle-locale--téléphone-conteneur-réseau) |
|
|
901
|
+
| `421 Misdirected Request` depuis un autre appareil | `domainCheck` actif, et cet hôte absent de `trustedHosts` | ajouter l'IP ou le nom à `trustedHosts` du module HTTP |
|
|
902
|
+
| Page blanche sur un appareil ancien (TV, vieux Safari) | le client cible ES2022 | `@vitejs/plugin-legacy` côté application — voir [Compatibilité](../../../../../docs/guides/compatibilite.md#navigateurs--la-cible-du-client) |
|
|
903
|
+
| `Refused to load the script` (politique de sécurité) | page rendue avant que Vite soit prêt : le fragment de développement n'est pas encore déclaré | recharger une fois Vite prêt ; vérifier que le nonce est bien propagé |
|
|
904
|
+
| Commentaire `prod manifest missing` dans la page | les bundles n'ont pas été construits, et Vite n'était pas là pour le faire au démarrage | `npm run build` (ou `npx nodefony frontend:build`) puis **recharge la page** — l'absence de manifeste n'est jamais mise en cache (`loadManifest()`, `TemplateHelper.ts:386`), le serveur voit le build sans redémarrer |
|
|
877
905
|
| Les assets répondent 404 en production | le serveur statique est absent ou le préfixe ne correspond pas | vérifier le montage journalisé au démarrage, et `publicPath` |
|
|
878
906
|
| Un module à interface est invisible de `listEntries()` | il est en mode `static` — il n'appelle jamais `registerEntry` | attendu ; regarder la molette `ui` et le mode journalisé au démarrage |
|
|
879
907
|
| Modifications du front sans effet | `vite.config.generated.mjs` édité à la main | ne jamais l'éditer : il est réécrit à chaque démarrage |
|