@nodefony/frontend 10.0.0-alpha.8 → 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.
- package/dist/_virtual/{_@oxc-project_runtime@0.150.0 → _@oxc-project_runtime@0.151.0}/helpers/esm/decorate.js +1 -1
- package/dist/_virtual/{_@oxc-project_runtime@0.150.0 → _@oxc-project_runtime@0.151.0}/helpers/esm/decorateMetadata.js +1 -1
- package/dist/index.js +2 -2
- package/dist/nodefony/service/FrontendService.js +5 -3
- package/dist/nodefony/service/ViteConfigGenerator.js +1 -1
- package/dist/nodefony/src/isolationGroups.js +1 -1
- package/dist/nodefony/src/remoteDev.js +33 -1
- package/dist/types/nodefony/src/isolationGroups.d.ts +1 -1
- package/dist/types/nodefony/src/remoteDev.d.ts +28 -0
- package/docs/index.md +58 -54
- package/package.json +10 -11
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
//#region \0@oxc-project+runtime@0.
|
|
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.
|
|
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.
|
|
14
|
-
import __decorate from "./_virtual/_@oxc-project_runtime@0.
|
|
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.
|
|
9
|
-
import __decorate from "../../_virtual/_@oxc-project_runtime@0.
|
|
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/
|
|
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/
|
|
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:
|
|
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:
|
|
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
|
|
99
|
-
|
|
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": "
|
|
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,
|
|
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:
|
|
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:
|
|
341
|
-
et gèle au démarrage ; `frontendConfigJsonSchema()` (`defineModuleConfig.ts:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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,
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
déclenche une boucle de rechargement.
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
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:
|
|
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:
|
|
572
|
-
| Vite ne répond plus (gelé) | sonde périodique ; après N échecs, Vite est tué pour être relancé (`ViteProcessSupervisor.ts:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
764
|
-
Vue (`vue3-vite.ts:11`), Angular (`angular-vite.ts:15`),
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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.
|
|
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": "
|
|
17
|
+
"build": "rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
|
|
18
18
|
"dev": "rolldown -c rolldown.config.ts --watch",
|
|
19
|
-
"clean": "
|
|
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.
|
|
40
|
-
"@nodefony/http": "^10.0.0-alpha.
|
|
41
|
-
"nodefony": "^10.0.0-alpha.
|
|
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.
|
|
46
|
-
"@nodefony/http": "^10.0.0-alpha.
|
|
45
|
+
"@nodefony/framework": "^10.0.0-alpha.9",
|
|
46
|
+
"@nodefony/http": "^10.0.0-alpha.9",
|
|
47
47
|
"@types/chai": "5.2.3",
|
|
48
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.
|
|
52
|
-
"
|
|
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,
|