@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.
Files changed (25) hide show
  1. package/README.md +56 -68
  2. package/dist/_virtual/{_@oxc-project_runtime@0.151.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorate.js +1 -1
  3. package/dist/_virtual/{_@oxc-project_runtime@0.151.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorateMetadata.js +1 -1
  4. package/dist/index.js +2 -2
  5. package/dist/nodefony/config/config.js +3 -8
  6. package/dist/nodefony/service/FrontendService.js +73 -295
  7. package/dist/nodefony/service/ViteConfigGenerator.js +11 -30
  8. package/dist/nodefony/service/ViteProcessSupervisor.js +17 -12
  9. package/dist/nodefony/service/bootSummary.js +44 -0
  10. package/dist/nodefony/src/isolationGroups.js +27 -32
  11. package/dist/nodefony/src/template/TemplateHelper.js +52 -19
  12. package/dist/types/nodefony/config/config.d.ts +0 -8
  13. package/dist/types/nodefony/interfaces/IFrontBuilder.d.ts +0 -9
  14. package/dist/types/nodefony/interfaces/IFrontendService.d.ts +6 -10
  15. package/dist/types/nodefony/interfaces/IViteSupervisor.d.ts +11 -5
  16. package/dist/types/nodefony/service/FrontendService.d.ts +24 -118
  17. package/dist/types/nodefony/service/ViteConfigGenerator.d.ts +13 -21
  18. package/dist/types/nodefony/service/ViteProcessSupervisor.d.ts +13 -16
  19. package/dist/types/nodefony/service/bootSummary.d.ts +23 -0
  20. package/dist/types/nodefony/src/isolationGroups.d.ts +24 -23
  21. package/dist/types/nodefony/src/template/TemplateHelper.d.ts +23 -7
  22. package/docs/index.md +173 -145
  23. package/package.json +12 -13
  24. package/dist/nodefony/src/remoteDev.js +0 -216
  25. 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-07-19
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 et se partagent le travail.
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 · 5151<br/>route → contrôleur → HTML"]
38
- NF -->|2 · HTML + balises script| BR
39
- BR -->|3 · assets, modules, HMR| VITE["Vite · 5173<br/>processus séparé"]
40
- BR -->|4 · fetch /shop/api| VITE
41
- VITE -->|proxy| NF
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 toujours de Nodefony (1-2) ; les **modules
46
- JavaScript** viennent de Vite en direct (3), donc ton serveur n'est jamais sur le chemin critique des
47
- assets ; et les **appels d'API** repartent vers Nodefony par le proxy de Vite (4). En production, Vite
48
- disparaît : les assets sont pré-construits et servis en fichiers statiques.
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:418`). La
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:163`).
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. [`apiProxyPaths`](#apiproxypaths--que-le-fetch-atteigne-le-serveur) — **à ne pas sauter** : c'est
116
- l'oubli qui produit le bug n°1 du module.
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
- | [`apiProxyPaths`](#apiproxypaths--que-le-fetch-atteigne-le-serveur) | que les appels d'API atteignent ton serveur | ton interface parle à ton back (donc oui) |
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 trois choses : quel framework, quel fichier d'entrée, quels chemins d'API proxifier. Tout le reste a un défaut sensé.",
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": "apiProxyPaths", "href": "#apiproxypaths--que-le-fetch-atteigne-le-serveur",
159
- "desc": "En développement ton interface vient de Vite : un fetch part donc vers Vite, qui ne connaît pas la route et répond son index.html. Le symptôme (Unexpected token '<') ne parle jamais de proxy — et le data plane d'administration, lui, est proxifié d'office.",
160
- "meta": "à ne pas sauter : c'est l'oubli qui produit le bug n°1" },
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. `https: true` réutilise les certificats de Nodefony :
202
- // à activer si tu ouvres ta page en https (sinon le navigateur bloque le
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 — d'où la déclaration `apiProxyPaths`. */
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:115`) : il n'est résolvable que par Vite quand
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 et porte déjà les balises Vite
316
- curl -s http://localhost:5151/shop | grep -o 'src="http[^"]*"'
317
- # src="http://127.0.0.1:5173/@vite/client"
318
- # src="http://127.0.0.1:5173/@fs/…/shop/frontend/src/main.tsx"
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
- # L'API répond en JSON — et le même appel depuis le navigateur passe par le proxy Vite
321
- curl -s http://localhost:5151/shop/api/products
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"` | Hôte de Vite, tel quel dans les `<script>` — doit être joignable du navigateur. |
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
- ### Le proxy vers ton serveur
362
-
363
- | Option | Type | Défaut | Effet |
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: déclare les origines Vite au pare-feu (CSP)
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 ne doit démarrer qu'une fois les serveurs
483
- Nodefony en écoute (`FrontendService.init()`, `FrontendService.ts:160`). Dans l'autre ordre, le proxy
484
- de Vite viserait un serveur inexistant et les premiers appels d'API échoueraient — un défaut
485
- intermittent, apparaissant seulement quand le navigateur est plus rapide que le démarrage.
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:69`) |
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` en **URL absolue** vers Vite — sans quoi un import transformé en `/src/App.tsx` serait
510
- résolu contre l'origine de Nodefony, donc en 404 ;
511
- - `strictPort` activé dès que cette base est posée : si Vite glissait de port, la base mentirait en
512
- silence ;
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
- ### `apiProxyPaths` — que le `fetch` atteigne le serveur
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
- Ta page est chargée depuis Vite. Un `fetch("/shop/api/products")` part donc vers **Vite** (port 5173),
524
- pas vers Nodefony. Vite ne connaît pas cette route ; comme tout serveur de développement d'application
525
- monopage, il répond alors son `index.html`. Ton code reçoit du HTML là où il attendait du JSON :
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
- 1. **Les préfixes de tous les modules sont agrégés et dédupliqués** — un seul Vite, un seul proxy.
536
- 2. **Une clé commençant par `^` est traitée comme une expression régulière** par Vite. C'est ainsi que
537
- le data plane d'administration est couvert d'un coup.
538
- 3. **`/nodefony/<module>/api` est ajouté d'office**, sans que tu le déclares (`ViteConfigGenerator.ts:201`).
539
- Sans cela, la barre de débogage injectée en développement appellerait `/nodefony/profiler/api` et
540
- recevrait le repli SPA — le clic serait mort.
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:84`) de taille `portRetryAttempts + 1` : ainsi, une instance
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:56`).
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:340`).
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:729`) |
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:266`) |
578
- | Arrêt du kernel | `SIGINT`, puis `SIGKILL` après 3 s — aucun zombie ne bloque le port (`ViteProcessSupervisor.ts:912`) |
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:984`) : sans cela, les relances successives les
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:254`) est appelée par le module consommateur,
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:40`).
610
-
611
- | Champ | Requis | Défaut | Rôle |
612
- | --------------- | ------ | ------------------ | --------------------------------------------------------------- |
613
- | `type` | oui | — | Le preset : `react19`, `vue3`, `angular`, `svelte5`, `vanilla`. |
614
- | `entry` | oui | — | Le fichier d'entrée, relatif à la racine du module. |
615
- | `root` | non | `./frontend` | La racine front (celle qui contient `index.html`). |
616
- | `outDir` | non | `./public/dist` | Où le build écrit ce bundle. |
617
- | `name` | non | nom du module | Nom logique du bundle — c'est la clé de `renderTags(...)`. |
618
- | `publicPath` | non | `/_assets/<name>/` | Préfixe d'URL des assets en production. |
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:926`) lit l'`index.html` **de ton module**, retire le `<script>`
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:163`) :
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:267`) ;
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:293`).
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:562`) — inspirés des helpers d'assets de Symfony :
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:799`) appelle Vite **entrée par entrée**, et non une
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:886`) — le scan est borné au dossier front et saute
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:705`) vérifie le manifeste de chaque entrée AVANT de monter les statics.
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:62`). Chaque bundle a donc son espace, sans collision
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:705`) monte chaque dossier de sortie sur son
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:326`) lit `manifest.json` — la carte produite par Vite — et
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:400`), sans quoi le style
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:69`). Un nouveau type doit être ajouté aux
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. Or en développement, tes modules viennent du port 5173 alors que ta page vient du 5151 :
789
- **tout** serait bloqué.
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
- La solution retenue n'est pas d'affaiblir la politique, mais de la **composer**. Une fois Vite prêt
792
- (donc ses ports réellement connus), le service déclare ses origines au pare-feu
793
- (`#registerCsp()`, `FrontendService.ts:1012`), qui émet **un seul** en-tête, origines fusionnées et
794
- nonce par requête. À l'arrêt, les origines sont retirées et la politique redevient stricte.
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 déclaré (`#viteCspFragment()`, `FrontendService.ts:1034`) mérite deux explications, parce
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
- Les origines sont générées pour tous les hôtes légitimes de développement — boucle locale, domaine du
807
- kernel, hôtes de confiance déclarés au module HTTP — croisés avec les ports Vite réels. Sans cela,
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:974`) — sans quoi les relances les accumuleraient.
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 : le préfixe d'API n'est pas proxifié | déclarer `apiProxyPaths: ["/mon/api"]` dans `registerEntry` |
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 refuse le certificat de Vite | certificat auto-signé sur une origine distincte | l'accepter sur l'origine Vite, ou installer l'autorité racine de développement |
875
- | `Refused to load the script` (politique de sécurité) | le pare-feu n'a pas les origines Vite (Vite pas encore prêt au rendu) | recharger une fois Vite prêt ; vérifier que le nonce est bien propagé |
876
- | 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:376`), le serveur voit le build sans redémarrer |
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 |