@nodefony/frontend 10.0.0-alpha.7 → 10.0.0-alpha.9

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.
@@ -1,4 +1,4 @@
1
- //#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorate.js
1
+ //#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorate.js
2
2
  function __decorate(decorators, target, key, desc) {
3
3
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
4
4
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -1,4 +1,4 @@
1
- //#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorateMetadata.js
1
+ //#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorateMetadata.js
2
2
  function __decorateMetadata(k, v) {
3
3
  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
4
4
  }
package/dist/index.js CHANGED
@@ -10,8 +10,8 @@ import { ViteBuilder } from "./nodefony/src/builders/ViteBuilder.js";
10
10
  import { ViteConfigGenerator } from "./nodefony/service/ViteConfigGenerator.js";
11
11
  import { ViteProcessSupervisor } from "./nodefony/service/ViteProcessSupervisor.js";
12
12
  import { TemplateHelper } from "./nodefony/src/template/TemplateHelper.js";
13
- import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorateMetadata.js";
14
- import __decorate from "./_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorate.js";
13
+ import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorateMetadata.js";
14
+ import __decorate from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorate.js";
15
15
  import FrontendService_default from "./nodefony/service/FrontendService.js";
16
16
  import { buildFrontendStatus, createFrontendAdminApi } from "./nodefony/src/FrontendAdminApi.js";
17
17
  import FrontendBuild from "./nodefony/command/frontend-build.js";
@@ -1,12 +1,12 @@
1
1
  import config from "../config/config.js";
2
2
  import { FrontendNoEntriesError, FrontendSupervisorStartError } from "../src/errors/FrontendError.js";
3
3
  import { ViteBuilder } from "../src/builders/ViteBuilder.js";
4
- import { allowedHostPatternForTemplate, detectRemoteDev, isLoopbackHostname, isValidOriginTemplate, viteAllowedHostFromPattern } from "../src/remoteDev.js";
4
+ import { allowedHostPatternForTemplate, detectRemoteDev, isLoopbackHostname, isValidOriginTemplate, remoteDevListenAdvice, viteAllowedHostFromPattern } from "../src/remoteDev.js";
5
5
  import { ViteProcessSupervisor } from "./ViteProcessSupervisor.js";
6
6
  import { TemplateHelper } from "../src/template/TemplateHelper.js";
7
7
  import { familyPortBlocks, familyPortPlan, isolationGroup } from "../src/isolationGroups.js";
8
- import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorateMetadata.js";
9
- import __decorate from "../../_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorate.js";
8
+ import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorateMetadata.js";
9
+ import __decorate from "../../_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorate.js";
10
10
  import { FRONTEND_CHOICES, Module, Service, extend, injectable, stripTrailingSlashes } from "nodefony";
11
11
  import path from "node:path";
12
12
  import fs from "node:fs";
@@ -208,6 +208,8 @@ let FrontendService = class FrontendService extends Service {
208
208
  const backendOrigin = `${this.cfg.backendProtocol}://${this.cfg.backendHost}:${this.resolveBackendPort()}`;
209
209
  const https = this.resolveHttps();
210
210
  const pinned = this.resolvePublicOrigin();
211
+ const conseil = remoteDevListenAdvice(detectRemoteDev(process.env), this.cfg.devHost);
212
+ if (conseil) this.log(conseil, "WARNING");
211
213
  const publicOriginTemplate = pinned?.template;
212
214
  this.originPinnedBy = pinned?.source ?? null;
213
215
  const allowedHosts = this.viteAllowedHosts(publicOriginTemplate);
@@ -44,7 +44,7 @@ var ViteConfigGenerator = class {
44
44
  case "angular": {
45
45
  imports.push(`import angular from "@analogjs/vite-plugin-angular";`);
46
46
  const tsconfigPath = toGeneratedPath(path.resolve(angularEntry.root, "tsconfig.app.json"));
47
- pluginsExprs.push(`angular({ tsconfig: ${JSON.stringify(tsconfigPath)} })`);
47
+ pluginsExprs.push(`angular({ disableTypeChecking: false, tsconfig: ${JSON.stringify(tsconfigPath)} })`);
48
48
  optimizeInclude.push("@angular/core", "@angular/common", "@angular/platform-browser");
49
49
  break;
50
50
  }
@@ -47,7 +47,7 @@ function isolationGroup(type) {
47
47
  /**
48
48
  * Famille servie sur le port de base (`devPort`). Les autres familles prennent
49
49
  * les blocs de ports suivants. Garder `default` ici garantit que l'instance
50
- * principale (React/Vue/Studio) reste sur le port habituel (5173).
50
+ * principale (React/Svelte/vanilla/Studio) reste sur le port habituel (5173).
51
51
  */
52
52
  const PRIMARY_FAMILY = "default";
53
53
  /**
@@ -156,6 +156,38 @@ function viteAllowedHostFromPattern(pattern) {
156
156
  return null;
157
157
  }
158
158
  /**
159
+ * Ce qu'il faut DIRE quand l'écoute du serveur Vite contredit la plateforme.
160
+ *
161
+ * Le symptôme que cette fonction existe pour expliquer : en dev déporté
162
+ * (Codespaces, Gitpod, conteneur, machine distante en SSH), la page se charge,
163
+ * aucun script ne démarre, et le navigateur rend `ERR_CONNECTION_REFUSED`. Rien
164
+ * ne relie ce refus à une adresse d'écoute — l'utilisateur ne peut pas deviner
165
+ * que le port existe mais n'est joignable que depuis la machine qui sert.
166
+ *
167
+ * **On AVERTIT, on n'ajuste pas.** Élargir l'écoute à toutes les interfaces est
168
+ * un geste RÉSEAU : il expose un port au-delà de la machine, et le framework ne
169
+ * le fait nulle part ailleurs en silence. Ce qui manquait n'était pas la
170
+ * capacité, c'était l'énoncé.
171
+ *
172
+ * Le message nomme les DEUX causes, et c'est délibéré : un message qui n'en
173
+ * énonce qu'une est cru PARCE QU'il est précis, et envoie chercher là où il n'y
174
+ * a rien. L'écoute est la première à vérifier ; le nom non déclaré de confiance
175
+ * produit exactement le même écran vide une fois l'écoute élargie.
176
+ *
177
+ * Pure, et l'environnement entre en paramètre : le cas se contrôle sans
178
+ * Codespace, sans conteneur et sans réseau.
179
+ *
180
+ * @param detection - ce que `detectRemoteDev` a rendu (`null` = pas de dev déporté).
181
+ * @param listenHost - l'adresse d'écoute configurée (`frontend.devHost`).
182
+ * @returns le message à journaliser, ou `null` quand il n'y a rien à dire —
183
+ * pas de plateforme distante, ou écoute déjà ouverte au-delà de la machine.
184
+ */
185
+ function remoteDevListenAdvice(detection, listenHost) {
186
+ if (!detection) return null;
187
+ if (!isLoopbackHostname(listenHost)) return null;
188
+ return `dev déporté détecté (${detection.provider}) mais Vite écoute sur « ${listenHost} » — une adresse d'ÉCOUTE locale. Depuis l'extérieur de cette machine (ou de ce conteneur), ce port n'est PAS joignable : la page se charge, aucun script ne démarre, et le navigateur rend ERR_CONNECTION_REFUSED.\n → écouter sur toutes les interfaces : frontend.devHost = "0.0.0.0" (geste réseau — il expose ce port au-delà de la machine, c'est pourquoi il n'est pas posé tout seul).\n Si la page reste muette une fois l'écoute élargie, la cause est ailleurs : le nom par lequel le navigateur arrive doit être déclaré de confiance (http.trustedHosts), sinon l'origine des assets n'est pas dérivée du « Host » reçu.`;
189
+ }
190
+ /**
159
191
  * Détecte un environnement de dev déporté depuis les variables de plateforme
160
192
  * (variables qu'on ne possède pas — elles se lisent, ne se renomment pas).
161
193
  * Ordre : Codespaces puis Gitpod (jamais les deux posées en pratique).
@@ -181,4 +213,4 @@ function detectRemoteDev(env) {
181
213
  return null;
182
214
  }
183
215
  //#endregion
184
- export { PORT_PLACEHOLDER, allowedHostPatternForTemplate, browserReachableHost, detectRemoteDev, isLoopbackHostname, isValidOriginTemplate, originWithHostname, resolveOriginTemplate, viteAllowedHostFromPattern };
216
+ export { PORT_PLACEHOLDER, allowedHostPatternForTemplate, browserReachableHost, detectRemoteDev, isLoopbackHostname, isValidOriginTemplate, originWithHostname, remoteDevListenAdvice, resolveOriginTemplate, viteAllowedHostFromPattern };
@@ -40,7 +40,7 @@ export declare function isolationGroup(type: string): string;
40
40
  /**
41
41
  * Famille servie sur le port de base (`devPort`). Les autres familles prennent
42
42
  * les blocs de ports suivants. Garder `default` ici garantit que l'instance
43
- * principale (React/Vue/Studio) reste sur le port habituel (5173).
43
+ * principale (React/Svelte/vanilla/Studio) reste sur le port habituel (5173).
44
44
  */
45
45
  export declare const PRIMARY_FAMILY = "default";
46
46
  /**
@@ -115,6 +115,34 @@ export declare function allowedHostPatternForTemplate(template: string): string
115
115
  * clair dans `trustedHosts` si le cas se présente).
116
116
  */
117
117
  export declare function viteAllowedHostFromPattern(pattern: string): string | null;
118
+ /**
119
+ * Ce qu'il faut DIRE quand l'écoute du serveur Vite contredit la plateforme.
120
+ *
121
+ * Le symptôme que cette fonction existe pour expliquer : en dev déporté
122
+ * (Codespaces, Gitpod, conteneur, machine distante en SSH), la page se charge,
123
+ * aucun script ne démarre, et le navigateur rend `ERR_CONNECTION_REFUSED`. Rien
124
+ * ne relie ce refus à une adresse d'écoute — l'utilisateur ne peut pas deviner
125
+ * que le port existe mais n'est joignable que depuis la machine qui sert.
126
+ *
127
+ * **On AVERTIT, on n'ajuste pas.** Élargir l'écoute à toutes les interfaces est
128
+ * un geste RÉSEAU : il expose un port au-delà de la machine, et le framework ne
129
+ * le fait nulle part ailleurs en silence. Ce qui manquait n'était pas la
130
+ * capacité, c'était l'énoncé.
131
+ *
132
+ * Le message nomme les DEUX causes, et c'est délibéré : un message qui n'en
133
+ * énonce qu'une est cru PARCE QU'il est précis, et envoie chercher là où il n'y
134
+ * a rien. L'écoute est la première à vérifier ; le nom non déclaré de confiance
135
+ * produit exactement le même écran vide une fois l'écoute élargie.
136
+ *
137
+ * Pure, et l'environnement entre en paramètre : le cas se contrôle sans
138
+ * Codespace, sans conteneur et sans réseau.
139
+ *
140
+ * @param detection - ce que `detectRemoteDev` a rendu (`null` = pas de dev déporté).
141
+ * @param listenHost - l'adresse d'écoute configurée (`frontend.devHost`).
142
+ * @returns le message à journaliser, ou `null` quand il n'y a rien à dire —
143
+ * pas de plateforme distante, ou écoute déjà ouverte au-delà de la machine.
144
+ */
145
+ export declare function remoteDevListenAdvice(detection: IRemoteDevDetection | null, listenHost: string): string | null;
118
146
  /**
119
147
  * Détecte un environnement de dev déporté depuis les variables de plateforme
120
148
  * (variables qu'on ne possède pas — elles se lisent, ne se renomment pas).
package/docs/index.md CHANGED
@@ -84,19 +84,19 @@ qui remplace Vite une fois en production.
84
84
  ### La vision Nodefony — ce que ce module fait différemment
85
85
 
86
86
  **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:372`). La
87
+ `child_process.spawn` (`ViteProcessSupervisor.attemptSpawn()`, `ViteProcessSupervisor.ts:414`). La
88
88
  conséquence est concrète : compiler dix mille modules ne coûte **rien** à la latence de tes requêtes,
89
89
  et un plantage de Vite ne tue pas ton serveur — le superviseur le relance tout seul.
90
90
 
91
91
  **C'est Nodefony qui sert le HTML.** Beaucoup de piles séparent un serveur front (qui rend la page) et
92
92
  un serveur d'API (qui rend le JSON). Ici, la page d'entrée reste une route de ton contrôleur :
93
93
  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:153`).
94
+ **injecter les bonnes balises** (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts:163`).
95
95
 
96
96
  **Un seul Vite pour N modules.** Trois modules à interface ne lancent pas trois serveurs Vite : leurs
97
97
  entrées sont agrégées dans une seule instance multi-entrées. La seule exception est documentée et
98
- justifiée — Angular est isolé, parce que son greffon transforme **tous** les `.ts` du serveur de
99
- développement (`isolationGroup()`, `isolationGroups.ts:39`).
98
+ justifiée — Angular et Vue sont isolés, parce qu'un greffon voisin transformerait leurs `.ts`
99
+ (`isolationGroup()`, `isolationGroups.ts:39`).
100
100
 
101
101
  **Le module ne dépend ni de `@nodefony/http` ni de `@nodefony/framework`.** Tout ce dont il a besoin
102
102
  d'eux (le serveur statique, le pare-feu, les certificats, le port réellement écouté) est résolu **par
@@ -159,10 +159,10 @@ Le tableau pour situer en cinq secondes ; les fiches en dessous pour savoir quoi
159
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
160
  "meta": "à ne pas sauter : c'est l'oubli qui produit le bug n°1" },
161
161
  { "icon": "🎨", "title": "Presets", "href": "#-extension",
162
- "desc": "Quatre recettes prêtes — React, Vue, Angular, 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.",
162
+ "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
163
  "meta": "tu choisis ton framework UI, ou tu en ajoutes un" },
164
164
  { "icon": "🧱", "title": "Familles d'isolation", "href": "#familles-disolation--pourquoi-angular-a-son-vite",
165
- "desc": "React, Vue et vanilla partagent une instance Vite sans se gêner. Angular non : son greffon transforme tout fichier .ts du serveur, y compris ceux des autres bundles — d'où une instance dédiée, sur son propre bloc de ports.",
165
+ "desc": "React, Svelte et vanilla partagent une instance Vite. Angular et Vue ont chacun la leur, sur leur propre bloc de ports : le greffon Angular transforme tout fichier .ts du serveur, et celui de React mord sur le script d'un composant Vue.",
166
166
  "meta": "tu mélanges Angular avec autre chose" },
167
167
  { "icon": "🖼️", "title": "Rendu des balises", "href": "#rendu--des-balises-ou-un-document-complet",
168
168
  "desc": "Deux portes d'entrée pour la même source : renderTags (tu écris ta page, on injecte les balises) et renderDocument (tu écris ton index.html, on l'injecte dedans). Plus les helpers de vue disponibles dans tes templates Eta.",
@@ -302,7 +302,7 @@ d'entrée. Ton `index.html` est **le tien** : mets-y tes polices, tes méta, tes
302
302
 
303
303
  Le marqueur `<!--nodefony:frontend-->` indique **où** injecter les balises ; sans lui, elles sont
304
304
  posées avant `</head>`. Le `<script>` d'entrée que tu vois en bas est retiré automatiquement au rendu
305
- (`TemplateHelper.injectIntoHtml()`, `TemplateHelper.ts:105`) : il n'est résolvable que par Vite quand
305
+ (`TemplateHelper.injectIntoHtml()`, `TemplateHelper.ts:115`) : il n'est résolvable que par Vite quand
306
306
  Vite sert lui-même la page, ce qui n'est pas le cas ici.
307
307
 
308
308
  ### Ce qu'on observe
@@ -337,8 +337,8 @@ npx nodefony frontend:status
337
337
 
338
338
  Tout se déclare dans `nodefony.config.ts` via `use("@nodefony/frontend", { … })`. Le schéma Zod
339
339
  (`frontendConfigSchema`, `config.ts:108`) est la **source unique** des défauts : chaque `.default()`
340
- y vit, et nulle part ailleurs. Le builder `defineFrontendConfig()` (`defineModuleConfig.ts:22`) valide
341
- et gèle au démarrage ; `frontendConfigJsonSchema()` (`defineModuleConfig.ts:31`) expose le tout en
340
+ y vit, et nulle part ailleurs. Le builder `defineFrontendConfig()` (`defineModuleConfig.ts:23`) valide
341
+ et gèle au démarrage ; `frontendConfigJsonSchema()` (`defineModuleConfig.ts:35`) expose le tout en
342
342
  JSON Schema pour l'écran de configuration de Studio.
343
343
 
344
344
  > [!NOTE]
@@ -370,7 +370,7 @@ JSON Schema pour l'écran de configuration de Studio.
370
370
  > **`backendPort` n'est pas forcément le port écouté.** Avec une politique de port automatique, un
371
371
  > 5151 occupé fait glisser l'écoute sur 5153. Un proxy figé enverrait alors les appels de ton
372
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:471`) et journalise
373
+ > serveur lui-même (`FrontendService.resolveBackendPort()`, `FrontendService.ts:493`) et journalise
374
374
  > l'écart.
375
375
 
376
376
  ### Le build de production
@@ -480,7 +480,7 @@ sequenceDiagram
480
480
  ```
481
481
 
482
482
  **Pourquoi `onServersReady` et pas `onReady`.** Vite ne doit démarrer qu'une fois les serveurs
483
- Nodefony en écoute (`FrontendService.init()`, `FrontendService.ts:146`). Dans l'autre ordre, le proxy
483
+ Nodefony en écoute (`FrontendService.init()`, `FrontendService.ts:160`). Dans l'autre ordre, le proxy
484
484
  de Vite viserait un serveur inexistant et les premiers appels d'API échoueraient — un défaut
485
485
  intermittent, apparaissant seulement quand le navigateur est plus rapide que le démarrage.
486
486
 
@@ -489,12 +489,12 @@ intermittent, apparaissant seulement quand le navigateur est plus rapide que le
489
489
  | Pièce | Rôle | Ancre |
490
490
  | ----------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------- |
491
491
  | `FrontendService` | l'orchestrateur : entrées, familles, cycle de vie, rendu | `FrontendService.ts:70` |
492
- | `ViteProcessSupervisor` | lance, surveille, relance et arrête **un** processus Vite | `ViteProcessSupervisor.ts:215` |
492
+ | `ViteProcessSupervisor` | lance, surveille, relance et arrête **un** processus Vite | `ViteProcessSupervisor.ts:236` |
493
493
  | `ViteConfigGenerator` | écrit la configuration Vite (fonction pure, testée seule) | `ViteConfigGenerator.toMjs()` (`ViteConfigGenerator.ts:69`) |
494
494
  | `ViteBuilder` | construit l'objet de configuration Vite pour le build en processus | `ViteBuilder.buildViteConfig()` (`ViteBuilder.ts:95`) |
495
495
  | `TemplateHelper` | produit les balises (dev) ou lit le manifeste (prod) | `TemplateHelper.ts:36` |
496
496
  | `isolationGroups` | à quelle famille appartient un preset, et sur quel bloc de ports | `isolationGroup()` (`isolationGroups.ts:39`) |
497
- | `FrontendAdminApi` | la vue sûre de l'état, pour Studio | `buildFrontendStatus()` (`FrontendAdminApi.ts:139`) |
497
+ | `FrontendAdminApi` | la vue sûre de l'état, pour Studio | `buildFrontendStatus()` (`FrontendAdminApi.ts:147`) |
498
498
 
499
499
  ### Une configuration Vite écrite, pas passée
500
500
 
@@ -535,7 +535,7 @@ connaître :
535
535
  1. **Les préfixes de tous les modules sont agrégés et dédupliqués** — un seul Vite, un seul proxy.
536
536
  2. **Une clé commençant par `^` est traitée comme une expression régulière** par Vite. C'est ainsi que
537
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:172`).
538
+ 3. **`/nodefony/<module>/api` est ajouté d'office**, sans que tu le déclares (`ViteConfigGenerator.ts:201`).
539
539
  Sans cela, la barre de débogage injectée en développement appellerait `/nodefony/profiler/api` et
540
540
  recevrait le repli SPA — le clic serait mort.
541
541
 
@@ -545,20 +545,23 @@ connaître :
545
545
 
546
546
  ### Familles d'isolation — pourquoi Angular a son Vite
547
547
 
548
- React, Vue et vanilla ciblent des extensions disjointes (`.tsx`, `.vue`) et cohabitent sans conflit
549
- dans une seule instance. Angular, lui, transforme **tout** fichier `.ts` du serveur de développement,
550
- y compris ceux des autres bundles — il échoue alors sur des fichiers hors de son `tsconfig`, ce qui
551
- déclenche une boucle de rechargement.
552
-
553
- D'où le regroupement par **famille** (`isolationGroup()`, `isolationGroups.ts:20`) : `angular` a la
554
- sienne, tout le reste partage `default`. Chaque famille obtient un **bloc de ports disjoint**
555
- (`familyPortPlan()`, `isolationGroups.ts:63`) de taille `portRetryAttempts + 1` : ainsi, une instance
548
+ React, Svelte et vanilla cohabitent dans une seule instance. Deux frameworks ne le peuvent pas, pour
549
+ deux raisons différentes. Angular transforme **tout** fichier `.ts` du serveur de développement, y
550
+ compris ceux des autres bundles — il échoue alors sur des fichiers hors de son `tsconfig`, ce qui
551
+ déclenche une boucle de rechargement. Vue, lui, sert le script d'un composant sous un identifiant
552
+ qui finit par `.ts` (`Comp.vue?vue&type=script&lang.ts`) : le greffon React y injecte son
553
+ `$RefreshSig$()`, que rien ne définit hors d'une page React, et le composant ne se monte plus. Des
554
+ extensions différentes n'y changent rien, et l'option `exclude` du greffon React non plus.
555
+
556
+ D'où le regroupement par **famille** (`isolationGroup()`, `isolationGroups.ts:39`) : `angular` et
557
+ `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
556
559
  qui glisse de port sur conflit ne peut jamais empiéter sur le bloc d'une autre. La famille principale
557
560
  garde le port habituel (`PRIMARY_FAMILY`, `isolationGroups.ts:56`).
558
561
 
559
562
  **Les familles démarrent indépendamment.** Si Angular échoue, React continue de fonctionner : le
560
563
  démarrage n'échoue que si **aucune** famille n'a pu démarrer (`FrontendService.startDev()`,
561
- `FrontendService.ts:339`).
564
+ `FrontendService.ts:340`).
562
565
 
563
566
  ### Résilience — ce qui se passe quand Vite tombe
564
567
 
@@ -568,11 +571,11 @@ les processus meurent.
568
571
  | Situation | Réponse |
569
572
  | -------------------------- | ----------------------------------------------------------------------------------------------------- |
570
573
  | Port occupé au lancement | essai sur le port suivant, jusqu'à `portRetryAttempts` (`ViteProcessSupervisor.ts:297`) |
571
- | Vite plante | relance avec délai exponentiel plafonné (`scheduleRestart()`, `ViteProcessSupervisor.ts:674`) |
572
- | Vite ne répond plus (gelé) | sonde périodique ; après N échecs, Vite est tué pour être relancé (`ViteProcessSupervisor.ts:599`) |
574
+ | Vite plante | relance avec délai exponentiel plafonné (`scheduleRestart()`, `ViteProcessSupervisor.ts:715`) |
575
+ | Vite ne répond plus (gelé) | sonde périodique ; après N échecs, Vite est tué pour être relancé (`ViteProcessSupervisor.ts:787`) |
573
576
  | Deux `start()` concurrents | la promesse en cours est partagée — jamais deux processus |
574
577
  | Ctrl+C au terminal | le signal marque un arrêt **voulu** : pas de relance (`markShutdown`, `ViteProcessSupervisor.ts:266`) |
575
- | Arrêt du kernel | `SIGINT`, puis `SIGKILL` après 3 s — aucun zombie ne bloque le port (`ViteProcessSupervisor.ts:26`) |
578
+ | Arrêt du kernel | `SIGINT`, puis `SIGKILL` après 3 s — aucun zombie ne bloque le port (`ViteProcessSupervisor.ts:912`) |
576
579
 
577
580
  Deux subtilités valent d'être connues, parce qu'elles expliquent des comportements sinon
578
581
  incompréhensibles :
@@ -601,19 +604,19 @@ et dans les types du paquet — jamais recopiées ici, où elles se périmeraien
601
604
 
602
605
  ### `registerEntry` — la déclaration d'une interface
603
606
 
604
- `FrontendService.registerEntry()` (`FrontendService.ts:243`) est appelée par le module consommateur,
607
+ `FrontendService.registerEntry()` (`FrontendService.ts:254`) est appelée par le module consommateur,
605
608
  dans son `onKernelBoot()`. Elle résout les chemins relatifs, calcule le préfixe public et renvoie
606
609
  l'entrée résolue (`IResolvedFrontendEntry`, `IFrontBuilder.ts:40`).
607
610
 
608
- | Champ | Requis | Défaut | Rôle |
609
- | --------------- | ------ | ------------------ | ---------------------------------------------------------- |
610
- | `type` | oui | — | Le preset : `react19`, `vue3`, `angular`, `vanilla`. |
611
- | `entry` | oui | — | Le fichier d'entrée, relatif à la racine du module. |
612
- | `root` | non | `./frontend` | La racine front (celle qui contient `index.html`). |
613
- | `outDir` | non | `./public/dist` | Où le build écrit ce bundle. |
614
- | `name` | non | nom du module | Nom logique du bundle — c'est la clé de `renderTags(...)`. |
615
- | `publicPath` | non | `/_assets/<name>/` | Préfixe d'URL des assets en production. |
616
- | `apiProxyPaths` | non | `[]` | Les préfixes que Vite doit transmettre à Nodefony. |
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. |
617
620
 
618
621
  ```ts ignore
619
622
  frontend.registerEntry(this, {
@@ -641,12 +644,12 @@ const tags = frontend.renderTags("shop", context.cspNonce);
641
644
  const html = frontend.renderDocument("shop", context.cspNonce);
642
645
  ```
643
646
 
644
- `renderDocument` (`FrontendService.ts:904`) lit l'`index.html` **de ton module**, retire le `<script>`
647
+ `renderDocument` (`FrontendService.ts:926`) lit l'`index.html` **de ton module**, retire le `<script>`
645
648
  d'entrée source, injecte les balises au marqueur (ou avant `</head>`), et renvoie le document.
646
649
  Pas d'`index.html` ? Une coquille minimale est générée. En production, l'index est mis en cache ; en
647
650
  développement il est relu à chaque appel, pour que tes modifications de la coquille apparaissent.
648
651
 
649
- Ce qui est injecté en développement (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts:153`) :
652
+ Ce qui est injecté en développement (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts:163`) :
650
653
 
651
654
  1. le **préambule React Fast Refresh** pour les entrées `react19` — sans lui, `@vitejs/plugin-react`
652
655
  refuse de démarrer ;
@@ -656,7 +659,7 @@ Ce qui est injecté en développement (`TemplateHelper.renderDevTags()`, `Templa
656
659
  4. un pont qui relaie les événements de rechargement vers la barre de débogage, **sans ouvrir de
657
660
  seconde connexion** (`hmrBridgeTag()`, `TemplateHelper.ts:267`) ;
658
661
  5. la barre de débogage elle-même, résolue une fois et servie via Vite (`debugBarTag()`,
659
- `TemplateHelper.ts:252`).
662
+ `TemplateHelper.ts:293`).
660
663
 
661
664
  Quand Vite n'est pas prêt, le rendu ne lève **jamais** : il renvoie un commentaire HTML disant
662
665
  l'état. Une page dégradée reste une page.
@@ -696,14 +699,14 @@ et son manifeste — c'est ce qui rend le multi-modules possible et ce qui isole
696
699
  Quatre comportements à connaître :
697
700
 
698
701
  - **Idempotent.** Une entrée dont le manifeste est plus récent que ses sources est ignorée
699
- (`isBuildFresh()`, `FrontendService.ts:829`) — le scan est borné au dossier front et saute
702
+ (`isBuildFresh()`, `FrontendService.ts:879`) — le scan est borné au dossier front et saute
700
703
  `node_modules`. Relancer un déploiement ne recompile pas tout.
701
704
  - **Les échecs sont collectés, pas propagés.** Un bundle en échec n'arrête pas les autres ; la
702
705
  commande passe le code de sortie à `1` s'il en reste un — de quoi casser un pipeline sans masquer
703
706
  les autres résultats.
704
707
  - **Le résultat est un bilan** : construits / ignorés / en échec, journalisé et renvoyé.
705
708
  - **Un démarrage en production sans build se répare — ou se dénonce.** `setupProd()`
706
- (`FrontendService.ts:683`) vérifie le manifeste de chaque entrée AVANT de monter les statics.
709
+ (`FrontendService.ts:705`) vérifie le manifeste de chaque entrée AVANT de monter les statics.
707
710
  Manifeste absent et Vite installé (poste de développement, devDependencies présentes) : le build
708
711
  tourne **une fois au démarrage**, annoncé en WARNING — fini l'écran blanc après un
709
712
  `nodefony production --detach` lancé trop tôt. Manifeste absent et Vite introuvable (image de
@@ -727,7 +730,7 @@ page. Les trois restent alignés par construction — impossible d'en changer un
727
730
  deux autres.
728
731
 
729
732
  Défaut : `/_assets/<name>/`, normalisé avec ses barres obliques
730
- (`normalizePublicPath()`, `FrontendService.ts:50`). Chaque bundle a donc son espace, sans collision
733
+ (`normalizePublicPath()`, `FrontendService.ts:62`). Chaque bundle a donc son espace, sans collision
731
734
  entre modules.
732
735
 
733
736
  `assetBaseUrl` ajoute une couche : la base d'un CDN. Renseignée, elle préfixe la `base` du build et
@@ -739,18 +742,18 @@ use("@nodefony/frontend", { assetBaseUrl: "https://cdn.example.com" });
739
742
  // → <script src="https://cdn.example.com/_assets/shop/main-a1b2c3.js">
740
743
  ```
741
744
 
742
- En production, `setupProd()` (`FrontendService.ts:683`) monte chaque dossier de sortie sur son
745
+ En production, `setupProd()` (`FrontendService.ts:705`) monte chaque dossier de sortie sur son
743
746
  `publicPath` via le serveur statique — résolu **par nom**, jamais par import, pour ne pas créer de
744
747
  cycle. Si ce service est absent (proxy frontal, CDN devant), un avertissement le dit et rien n'est
745
748
  monté : c'est un déploiement valide, pas une panne.
746
749
 
747
750
  ### Ce qui est servi en production
748
751
 
749
- `renderProdTags()` (`TemplateHelper.ts:315`) lit `manifest.json` — la carte produite par Vite — et
752
+ `renderProdTags()` (`TemplateHelper.ts:326`) lit `manifest.json` — la carte produite par Vite — et
750
753
  émet, dans cet ordre : les feuilles de style d'abord (pour éviter le flash de contenu non stylé), les
751
754
  préchargements des morceaux partagés, puis le script d'entrée. Le manifeste est lu **une fois par
752
755
  dossier de sortie** et mis en cache : aucune lecture disque par requête. Le CSS est collecté
753
- récursivement à travers les imports (`collectCss()`, `TemplateHelper.ts:389`), sans quoi le style
756
+ récursivement à travers les imports (`collectCss()`, `TemplateHelper.ts:400`), sans quoi le style
754
757
  d'un morceau partagé manquerait sur certaines pages.
755
758
 
756
759
  Manifeste absent ? Un commentaire HTML le dit, avec la commande à lancer. Pas d'exception, pas de
@@ -758,10 +761,11 @@ page blanche muette.
758
761
 
759
762
  ## 🧩 Extension
760
763
 
761
- **Ajouter un framework UI** revient à écrire un preset (`IFrontPreset`, `IFrontPreset.ts:16`) : son
764
+ **Ajouter un framework UI** revient à écrire un preset (`IFrontPreset`, `IFrontPreset.ts:15`) : son
762
765
  identifiant, ses extensions, ses dépendances à pré-empaqueter, et une fonction qui construit ses
763
- greffons Vite. Les quatre presets fournis sont les modèles à copier — React (`react19-vite.ts:9`),
764
- Vue (`vue3-vite.ts:11`), Angular (`angular-vite.ts:15`), vanilla (`vanilla-vite.ts:9`). Tous
766
+ greffons Vite. Les cinq presets fournis sont les modèles à copier — React (`react19-vite.ts:9`),
767
+ Vue (`vue3-vite.ts:11`), Angular (`angular-vite.ts:15`), Svelte (`svelte5-vite.ts:13`),
768
+ vanilla (`vanilla-vite.ts:9`). Tous
765
769
  importent leur greffon **paresseusement** : un preset non utilisé ne coûte ni installation, ni
766
770
  chargement.
767
771
 
@@ -774,7 +778,7 @@ Deux points d'attention avant de se lancer :
774
778
  - si le nouveau framework transforme des fichiers qui ne lui appartiennent pas, il lui faut sa propre
775
779
  famille d'isolation — c'est la leçon d'Angular.
776
780
 
777
- **Remplacer le superviseur** est prévu par le contrat `IViteSupervisor` (`IViteSupervisor.ts:41`) :
781
+ **Remplacer le superviseur** est prévu par le contrat `IViteSupervisor` (`IViteSupervisor.ts:64`) :
778
782
  `start`, `stop`, `status`. C'est le seul point d'isolement entre « Vite dans un processus séparé » et
779
783
  toute autre stratégie.
780
784
 
@@ -786,10 +790,10 @@ origine. Or en développement, tes modules viennent du port 5173 alors que ta pa
786
790
 
787
791
  La solution retenue n'est pas d'affaiblir la politique, mais de la **composer**. Une fois Vite prêt
788
792
  (donc ses ports réellement connus), le service déclare ses origines au pare-feu
789
- (`#registerCsp()`, `FrontendService.ts:990`), qui émet **un seul** en-tête, origines fusionnées et
793
+ (`#registerCsp()`, `FrontendService.ts:1012`), qui émet **un seul** en-tête, origines fusionnées et
790
794
  nonce par requête. À l'arrêt, les origines sont retirées et la politique redevient stricte.
791
795
 
792
- Le fragment déclaré (`#viteCspFragment()`, `FrontendService.ts:1012`) mérite deux explications, parce
796
+ Le fragment déclaré (`#viteCspFragment()`, `FrontendService.ts:1034`) mérite deux explications, parce
793
797
  qu'elles piègent tout le monde :
794
798
 
795
799
  - **`'self'` est répété dans chaque directive.** `connect-src`, `style-src`, `img-src` et `font-src`
@@ -809,7 +813,7 @@ accéder à ton application par un hôte virtuel bloquerait tout.
809
813
  > fuirait jusqu'à un déploiement.
810
814
 
811
815
  Deux garde-fous complètent le tableau : le producteur de données pour Studio expose une vue **sans
812
- chemins de fichiers absolus** (`IViteInstanceView`, `FrontendAdminApi.ts:78`), et le serveur de
816
+ chemins de fichiers absolus** (`IViteInstanceView`, `FrontendAdminApi.ts:80`), et le serveur de
813
817
  développement n'autorise l'accès disque qu'aux racines explicitement listées.
814
818
 
815
819
  ## ⚡ Performance et mémoire
@@ -836,7 +840,7 @@ En ligne de commande, `nodefony frontend:status` donne l'état, le point d'écou
836
840
  entrées servies ; `-j` produit le même contenu en JSON, exploitable par un script.
837
841
 
838
842
  Côté data plane, le module enregistre son producteur au démarrage
839
- (`createFrontendAdminApi()`, `FrontendAdminApi.ts:165`) :
843
+ (`createFrontendAdminApi()`, `FrontendAdminApi.ts:173`) :
840
844
 
841
845
  | Route | Contenu |
842
846
  | --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
@@ -869,7 +873,7 @@ apparaisse avant le « prêt ».
869
873
  | `max restarts reached` | Vite plante en boucle | lire les lignes `[vite]` du journal — l'erreur est dans ton code front |
870
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 |
871
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é |
872
- | 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:336`), le serveur voit le build sans redémarrer |
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 |
873
877
  | 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` |
874
878
  | 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 |
875
879
  | Modifications du front sans effet | `vite.config.generated.mjs` édité à la main | ne jamais l'éditer : il est réécrit à chaque démarrage |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodefony/frontend",
3
- "version": "10.0.0-alpha.7",
3
+ "version": "10.0.0-alpha.9",
4
4
  "description": "Construction et rechargement à chaud des frontends de chaque module Nodefony — Vite intégré, multi-framework (React, Vue, Angular, Svelte)",
5
5
  "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
6
6
  "type": "module",
@@ -14,9 +14,9 @@
14
14
  }
15
15
  },
16
16
  "scripts": {
17
- "build": "rimraf dist && rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
17
+ "build": "rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
18
18
  "dev": "rolldown -c rolldown.config.ts --watch",
19
- "clean": "rimraf dist",
19
+ "clean": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
20
20
  "test": "vitest run",
21
21
  "test:integration": "vitest run --config vitest.integration.config.ts",
22
22
  "coverage": "vitest run --coverage",
@@ -36,21 +36,20 @@
36
36
  "esm"
37
37
  ],
38
38
  "peerDependencies": {
39
- "@nodefony/framework": "^10.0.0-alpha.7",
40
- "@nodefony/http": "^10.0.0-alpha.7",
41
- "nodefony": "^10.0.0-alpha.7",
39
+ "@nodefony/framework": "^10.0.0-alpha.9",
40
+ "@nodefony/http": "^10.0.0-alpha.9",
41
+ "nodefony": "^10.0.0-alpha.9",
42
42
  "zod": "^4.6.5"
43
43
  },
44
44
  "devDependencies": {
45
- "@nodefony/framework": "^10.0.0-alpha.7",
46
- "@nodefony/http": "^10.0.0-alpha.7",
45
+ "@nodefony/framework": "^10.0.0-alpha.9",
46
+ "@nodefony/http": "^10.0.0-alpha.9",
47
47
  "@types/chai": "5.2.3",
48
- "@types/node": "26.6.1",
48
+ "@types/node": "26.6.2",
49
49
  "@vitest/coverage-v8": "5.0.1",
50
50
  "chai": "6.2.2",
51
- "nodefony": "^10.0.0-alpha.7",
52
- "rimraf": "6.1.3",
53
- "vite": "8.3.0",
51
+ "nodefony": "^10.0.0-alpha.9",
52
+ "vite": "8.3.1",
54
53
  "vitest": "5.0.1"
55
54
  },
56
55
  "private": false,