@nodefony/frontend 10.0.0-beta.2 → 10.0.0-beta.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +38 -50
- package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorate.js +1 -1
- package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorateMetadata.js +1 -1
- package/dist/index.js +2 -2
- package/dist/nodefony/config/config.js +3 -8
- package/dist/nodefony/service/FrontendService.js +73 -295
- package/dist/nodefony/service/ViteConfigGenerator.js +11 -30
- package/dist/nodefony/service/ViteProcessSupervisor.js +17 -12
- package/dist/nodefony/service/bootSummary.js +44 -0
- package/dist/nodefony/src/isolationGroups.js +27 -32
- package/dist/nodefony/src/template/TemplateHelper.js +52 -19
- package/dist/types/nodefony/config/config.d.ts +0 -8
- package/dist/types/nodefony/interfaces/IFrontBuilder.d.ts +0 -9
- package/dist/types/nodefony/interfaces/IFrontendService.d.ts +6 -10
- package/dist/types/nodefony/interfaces/IViteSupervisor.d.ts +11 -5
- package/dist/types/nodefony/service/FrontendService.d.ts +24 -118
- package/dist/types/nodefony/service/ViteConfigGenerator.d.ts +13 -21
- package/dist/types/nodefony/service/ViteProcessSupervisor.d.ts +13 -16
- package/dist/types/nodefony/service/bootSummary.d.ts +23 -0
- package/dist/types/nodefony/src/isolationGroups.d.ts +24 -23
- package/dist/types/nodefony/src/template/TemplateHelper.d.ts +23 -7
- package/docs/index.md +173 -145
- package/package.json +12 -12
- package/dist/nodefony/src/remoteDev.js +0 -216
- package/dist/types/nodefony/src/remoteDev.d.ts +0 -152
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@ Vite a besoin d'un event-loop et d'un tas V8 pour compiler/HMR. L'exécuter **in
|
|
|
12
12
|
|
|
13
13
|
- Crash Vite ≠ crash Nodefony
|
|
14
14
|
- Compilation Vite ≠ latence event-loop Nodefony
|
|
15
|
-
- HMR WebSocket de Vite
|
|
15
|
+
- HMR WebSocket de Vite relayé par Nodefony, sur l'origine de la page
|
|
16
16
|
- Auto-restart en cas de mort du child (résilience built-in)
|
|
17
17
|
|
|
18
18
|
---
|
|
@@ -68,9 +68,6 @@ class MyModule extends Module {
|
|
|
68
68
|
root: "./frontend", // contient index.html
|
|
69
69
|
outDir: "./public/dist", // pour la prod build
|
|
70
70
|
name: "my-module", // nom logique (entryName)
|
|
71
|
-
// Quand le browser fait fetch("/my/api/x") depuis l'app Vite,
|
|
72
|
-
// Vite proxifie vers Nodefony :
|
|
73
|
-
apiProxyPaths: ["/my/api"],
|
|
74
71
|
});
|
|
75
72
|
return this;
|
|
76
73
|
}
|
|
@@ -126,18 +123,13 @@ class MyController extends Controller {
|
|
|
126
123
|
// origines Vite au firewall (`@nodefony/security`), qui émet UN seul
|
|
127
124
|
// en-tête. Un controller qui le réécrirait écraserait le nonce.
|
|
128
125
|
|
|
129
|
-
//
|
|
130
|
-
//
|
|
131
|
-
//
|
|
132
|
-
//
|
|
133
|
-
// qu'un poste et un navigateur en conteneur sont servis en même temps,
|
|
134
|
-
// sans configuration. Scheme et port restent ceux de Vite.
|
|
126
|
+
// Le nonce CSP de la requête est propagé au rendu : sans lui,
|
|
127
|
+
// `script-src 'nonce-…'` bloque les balises. En développement, les URLs
|
|
128
|
+
// vers Vite sont relatives à la page (`/_vite/<famille>/…`) : un poste et
|
|
129
|
+
// un navigateur en conteneur sont servis en même temps, sans configuration.
|
|
135
130
|
const viteTags =
|
|
136
|
-
svc?.renderTags(
|
|
137
|
-
|
|
138
|
-
this.context?.cspNonce,
|
|
139
|
-
this.context?.domain,
|
|
140
|
-
) ?? "<!-- @nodefony/frontend not started -->";
|
|
131
|
+
svc?.renderTags("my-module", this.context?.cspNonce) ??
|
|
132
|
+
"<!-- @nodefony/frontend not started -->";
|
|
141
133
|
|
|
142
134
|
return this.render(`<!DOCTYPE html>
|
|
143
135
|
<html lang="en">
|
|
@@ -167,7 +159,9 @@ INFO frontend : registered entry: my-module (react19) from "my-module"
|
|
|
167
159
|
INFO frontend : vite [default] ready on 127.0.0.1:5173
|
|
168
160
|
```
|
|
169
161
|
|
|
170
|
-
Va sur `
|
|
162
|
+
Va sur `https://127.0.0.1:5152/my-route/` — Nodefony rend l'HTML, et relaie à Vite tout ce qui passe sous `/_vite/<famille>/` (modules, styles, socket du rechargement à chaud). Le navigateur ne voit qu'**une** origine : un seul certificat, pas de contenu mixte. HMR fonctionne en édition de `App.tsx`.
|
|
163
|
+
|
|
164
|
+
Pour ouvrir la page depuis un téléphone du réseau local : `NF_BIND_ALL=true` (application générée), puis `https://<IP-de-ta-machine>:5152/my-route/` — détail dans la [documentation du module](docs/index.md#-hors-de-la-boucle-locale--téléphone-conteneur-réseau).
|
|
171
165
|
|
|
172
166
|
---
|
|
173
167
|
|
|
@@ -178,19 +172,11 @@ Dans le `config.ts` de **ton app** ou de **ton module** :
|
|
|
178
172
|
```ts
|
|
179
173
|
const config = {
|
|
180
174
|
"module-frontend": {
|
|
181
|
-
devHost: "127.0.0.1", //
|
|
182
|
-
devPort: 5173, // port Vite (incrémenté si occupé)
|
|
175
|
+
devHost: "127.0.0.1", // écoute de Vite — boucle locale, Nodefony le relaie
|
|
176
|
+
devPort: 5173, // port Vite interne (incrémenté si occupé)
|
|
183
177
|
autoStartInDevelopment: true, // démarre Vite en env=development
|
|
184
178
|
pipeViteLogs: true, // logs Vite dans syslog Nodefony
|
|
185
179
|
|
|
186
|
-
// HTTPS — partage les certs Nodefony (server-https 5152)
|
|
187
|
-
https: true, // false par défaut
|
|
188
|
-
|
|
189
|
-
// Proxy backend Vite → Nodefony
|
|
190
|
-
backendHost: "127.0.0.1",
|
|
191
|
-
backendPort: 5151,
|
|
192
|
-
backendProtocol: "http", // http | https
|
|
193
|
-
|
|
194
180
|
// Variables d'env passées à Vite (les VITE_* sont exposées au browser)
|
|
195
181
|
viteEnv: {
|
|
196
182
|
VITE_API_BASE: "/api/v1",
|
|
@@ -218,12 +204,12 @@ Tout est optionnel — les defaults fonctionnent out-of-the-box.
|
|
|
218
204
|
|
|
219
205
|
`FrontendService` est un `Service` Nodefony (donc un `EventEmitter`). Tu peux écouter :
|
|
220
206
|
|
|
221
|
-
| Event | Payload
|
|
222
|
-
| ------------------- |
|
|
223
|
-
| `frontend:starting` | `{
|
|
224
|
-
| `frontend:ready` | `IViteSupervisorStatus`
|
|
225
|
-
| `frontend:error` | `Error`
|
|
226
|
-
| `frontend:stopped` | (rien)
|
|
207
|
+
| Event | Payload | Quand |
|
|
208
|
+
| ------------------- | ----------------------- | --------------------------------------- |
|
|
209
|
+
| `frontend:starting` | `{ entries }` | Juste avant le spawn Vite |
|
|
210
|
+
| `frontend:ready` | `IViteSupervisorStatus` | Vite a annoncé `Local:` dans son stdout |
|
|
211
|
+
| `frontend:error` | `Error` | Spawn ou ready timeout échoué |
|
|
212
|
+
| `frontend:stopped` | (rien) | Après `stop()` propre (SIGINT envoyé) |
|
|
227
213
|
|
|
228
214
|
Exemple :
|
|
229
215
|
|
|
@@ -247,10 +233,10 @@ interface IFrontendService {
|
|
|
247
233
|
stopDev(): Promise<void>;
|
|
248
234
|
// vite.build() par entrée ; bilan construits / ignorés / en échec
|
|
249
235
|
build(opts?: { force?: boolean }): Promise<IFrontendBuildResult>;
|
|
250
|
-
// `nonce` = `Context.cspNonce` ;
|
|
251
|
-
//
|
|
252
|
-
renderTags(entryName, nonce
|
|
253
|
-
renderDocument(entryName, nonce
|
|
236
|
+
// `nonce` = `Context.cspNonce` ; en développement, les URLs vers Vite sont
|
|
237
|
+
// relatives à la page (`/_vite/<famille>/…`).
|
|
238
|
+
renderTags(entryName, nonce?): string;
|
|
239
|
+
renderDocument(entryName, nonce?): string;
|
|
254
240
|
assetUrl(path): string;
|
|
255
241
|
}
|
|
256
242
|
```
|
|
@@ -263,18 +249,15 @@ interface IFrontendService {
|
|
|
263
249
|
|
|
264
250
|
### Page blanche, scripts bloqués par CSP
|
|
265
251
|
|
|
266
|
-
En développement, le service déclare
|
|
267
|
-
Vite prêt
|
|
252
|
+
En développement, le service déclare son fragment CSP au pare-feu (`@nodefony/security`) une fois
|
|
253
|
+
Vite prêt — sans aucune origine, tout passe par celle de la page — et ce dernier émet UN seul
|
|
254
|
+
en-tête CSP avec le nonce de la requête. Vérifie que tu passes
|
|
268
255
|
`this.context?.cspNonce` à `svc.renderTags(…)` / `renderDocument(…)`, et ne réécris jamais l'en-tête
|
|
269
256
|
dans le contrôleur : tu écraserais le nonce.
|
|
270
257
|
|
|
271
258
|
### `Unexpected token '<'` sur `fetch("/api/...")`
|
|
272
259
|
|
|
273
|
-
Vite sert son SPA-fallback HTML pour les routes inconnues.
|
|
274
|
-
|
|
275
|
-
```ts
|
|
276
|
-
svc.registerEntry(this, { ..., apiProxyPaths: ["/my/api"] });
|
|
277
|
-
```
|
|
260
|
+
La page est ouverte sur le port de Vite, qui sert son SPA-fallback HTML pour les routes inconnues. Ouvre-la par Nodefony : le `fetch` part alors vers lui, sur l'origine de la page. Il n'y a pas de proxy d'API à déclarer — `apiProxyPaths` et les options `backendHost`/`backendPort`/`backendProtocol` ont été retirés.
|
|
278
261
|
|
|
279
262
|
### `@vitejs/plugin-react can't detect preamble`
|
|
280
263
|
|
|
@@ -284,9 +267,13 @@ Le `TemplateHelper` injecte automatiquement le preamble React Fast Refresh pour
|
|
|
284
267
|
|
|
285
268
|
Le port configuré est pris. Le supervisor retry automatiquement sur `port+1`, `port+2` (option `portRetryAttempts`). Vérifie le port résolu via `svc.status().port` — il vaut `null` tant qu'aucun port n'a été résolu, jamais le port demandé : un port qu'on espère n'est pas un port qui sert.
|
|
286
269
|
|
|
287
|
-
### Le
|
|
270
|
+
### Le navigateur alerte sur le certificat de développement
|
|
271
|
+
|
|
272
|
+
Accepte-le **une** fois sur la page : modules et socket passent par la même origine, donc par le même certificat. Ou installe la CA root Nodefony : `nodefony/config/certificates/ca/nodefony-root-ca.crt.pem` dans ton trousseau.
|
|
273
|
+
|
|
274
|
+
### Connexion refusée depuis un téléphone
|
|
288
275
|
|
|
289
|
-
|
|
276
|
+
En développement, l'application n'écoute que la boucle locale. `NF_BIND_ALL=true` l'ouvre au réseau local (application générée) — à réserver à un réseau de confiance.
|
|
290
277
|
|
|
291
278
|
### Vite crash en boucle (`max restarts reached`)
|
|
292
279
|
|
|
@@ -318,7 +305,8 @@ Kernel "onServersReady" ← 4 servers Nodefony écoutent
|
|
|
318
305
|
FrontendService.startDev()
|
|
319
306
|
↓
|
|
320
307
|
ViteProcessSupervisor.start()
|
|
321
|
-
├─ écrit vite.config.generated.mjs (
|
|
308
|
+
├─ écrit vite.config.generated.mjs (base /_vite/<famille>/, env)
|
|
309
|
+
├─ monte /_vite/<famille>/ sur le proxy inverse de @nodefony/http
|
|
322
310
|
├─ spawn(node, [vite.js, "--config", ...]) (repli npx si le binaire n'est pas résolu)
|
|
323
311
|
├─ parse stdout "Local: https://host:port" → state = "ready"
|
|
324
312
|
├─ attach exit handler (auto-restart si crash inattendu)
|
|
@@ -328,11 +316,11 @@ Browser GET /my-route/
|
|
|
328
316
|
│
|
|
329
317
|
Nodefony rend HTML + svc.renderTags() injecte:
|
|
330
318
|
<script type="module"> preamble React Fast Refresh
|
|
331
|
-
<script src="
|
|
332
|
-
<script src="
|
|
319
|
+
<script src="/_vite/default/@vite/client">
|
|
320
|
+
<script src="/_vite/default/@fs/…/src/main.tsx">
|
|
333
321
|
|
|
334
|
-
Browser →
|
|
335
|
-
Browser →
|
|
322
|
+
Browser → Nodefony (5152) /_vite/… → relais → Vite 127.0.0.1:5173 (assets + HMR WSS)
|
|
323
|
+
Browser → Nodefony (5152) /api/… → ton contrôleur, sans proxy
|
|
336
324
|
```
|
|
337
325
|
|
|
338
326
|
Détails internes (dans le dépôt) : voir [`CLAUDE.md`](https://github.com/nodefony/nodefony-core/blob/main/src/packages/@nodefony/frontend/CLAUDE.md) et [`MEMORY.md`](https://github.com/nodefony/nodefony-core/blob/main/src/packages/@nodefony/frontend/MEMORY.md).
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
//#region \0@oxc-project+runtime@0.
|
|
1
|
+
//#region \0@oxc-project+runtime@0.153.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.153.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.153.0/helpers/esm/decorateMetadata.js";
|
|
14
|
+
import __decorate from "./_virtual/_@oxc-project_runtime@0.153.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";
|
|
@@ -40,20 +40,15 @@ const resilienceSchema = z.strictObject({
|
|
|
40
40
|
portRetryAttempts: z.number().int().positive().default(3).describe("Nombre de ports à essayer sur `EADDRINUSE` (devPort, devPort+1, …). Défaut : 3.")
|
|
41
41
|
}).describe("Résilience du superviseur Vite (auto-restart, backoff, health check). Toutes optionnelles — les défauts internes s'appliquent si rien n'est fourni.");
|
|
42
42
|
const frontendConfigSchema = z.strictObject({
|
|
43
|
-
devHost: z.string().default("127.0.0.1").describe("
|
|
44
|
-
devPort: z.number().int().positive().default(5173).describe("Port d'écoute du dev server Vite (5173 par défaut) — port de BASE : chaque famille de frontends prend le bloc suivant. Si occupé, c'est le SUPERVISEUR qui relance sur le port suivant (`resilience.portRetryAttempts` essais) et publie le port réel dans son `status()` — Vite, lui, ne se décale jamais seul : le fichier généré porte `strictPort` pour que
|
|
45
|
-
publicOrigin: z.string().default("").refine((v) => v === "" || /^https?:\/\/[^/\s]+$/.test(v), { message: "publicOrigin doit être une origine (`scheme://host[:port]`), sans chemin" }).describe("Origine PUBLIQUE du dev server Vite — celle que le NAVIGATEUR utilise, quand elle diffère de l'adresse d'écoute (`devHost`). ÉPINGLE le rendu sur une origine unique : à réserver aux cas où un frontal la réécrit (tunnel, proxy, port remappé). Utilisée telle quelle (port inclus SEULEMENT si écrit) dans les `<script>` injectés, le `base` Vite et le WebSocket HMR (`hmr.host`/`clientPort`, dérivés). Vide (défaut, RECOMMANDÉ) = chaque page annonce l'origine par laquelle le client est arrivé (`Host` de la requête, scheme et port de Vite) : un poste et un navigateur en conteneur sont servis EN MÊME TEMPS par la même instance, sans configuration. Codespaces/Gitpod sont détectés automatiquement et fournissent alors l'origine par défaut — MAIS un client arrivé par la boucle locale (tunnel de port : VS Code Desktop le fait par défaut) reste servi en local, parce que l'origine publique d'une plateforme exige sa session, qu'une intégration continue ou une sonde n'a pas. Une origine écrite ICI, en revanche, gagne sur tout — c'est un réglage, pas une déduction. L'hôte d'une origine épinglée est automatiquement autorisé par Vite (`server.allowedHosts`) ; les hôtes suivis par la dérivation sont ceux de `trustedHosts` de @nodefony/http (une seule liste à maintenir : elle ouvre la barrière 421, Vite, le CSP et le rendu)."),
|
|
43
|
+
devHost: z.string().default("127.0.0.1").describe("Adresse d'écoute du dev server Vite. Défaut (RECOMMANDÉ) : la boucle locale — le navigateur ne joint jamais Vite directement, Nodefony le relaie sur l'origine de la page (`/_vite/<famille>/`). Prod : N/A (Vite ne tourne pas en prod, le manifest pilote)."),
|
|
44
|
+
devPort: z.number().int().positive().default(5173).describe("Port d'écoute du dev server Vite (5173 par défaut) — port de BASE : chaque famille de frontends prend le bloc suivant. Si occupé, c'est le SUPERVISEUR qui relance sur le port suivant (`resilience.portRetryAttempts` essais) et publie le port réel dans son `status()` — Vite, lui, ne se décale jamais seul : le fichier généré porte `strictPort` pour que le relais `/_vite/<famille>/` vise toujours le Vite qui sert. Le navigateur ne voit jamais ce port : il passe par l'origine de la page."),
|
|
46
45
|
autoStartInDevelopment: z.boolean().default(true).describe("Démarre automatiquement le superviseur Vite quand le kernel passe en `development`. Ignoré en `production`/`staging`. Reco : true en dev, sinon les helpers template injecteront une URL morte."),
|
|
47
46
|
defaultOutDir: z.string().default("./public/dist").describe("Dossier de sortie par défaut pour le build prod, relatif à la racine du module consommateur. Réécrit par la prop `outDir` de la déclaration d'entrée."),
|
|
48
47
|
defaultRoot: z.string().default("./frontend").describe("Racine front par défaut (contient `index.html`) côté module."),
|
|
49
48
|
assetBaseUrl: z.string().default("").describe("Base URL des assets servis en PRODUCTION (CDN / object storage / edge). Vide = assets servis depuis l'origine Nodefony en chemins relatifs (comportement historique). Renseignée (ex. `https://cdn.example.com`), elle préfixe le `base` Vite au build, les URLs de `renderProdTags` et le helper `asset('/x')`. N'affecte JAMAIS le mount `Statics`. Reco prod cloud-native : pointer le CDN devant l'object storage."),
|
|
50
49
|
startupTimeoutMs: z.number().int().positive().default(3e4).describe("Timeout (ms) d'attente du `Local: http://…` dans le stdout Vite avant de considérer le démarrage comme cassé. Dev : 30s suffisent pour un cold-start Vite. Prod : N/A."),
|
|
51
50
|
pipeViteLogs: z.boolean().default(true).describe("Propage les logs Vite vers le syslog Nodefony (sinon ils restent dans le stdout du process enfant uniquement)."),
|
|
52
|
-
|
|
53
|
-
backendPort: z.number().int().positive().default(5151).describe("Port du serveur Nodefony cible du proxy Vite. HTTP par défaut (5151, config par défaut de `@nodefony/http`). Ajuster si l'app surcharge."),
|
|
54
|
-
backendProtocol: z.enum(["http", "https"]).default("http").describe("Protocole du proxy Vite vers Nodefony. `http` par défaut — `https` pour proxifier vers le serveur HTTPS Nodefony (5152). Avec `https` et un certificat self-signed, prévoir `secure: false` côté proxy."),
|
|
55
|
-
https: z.boolean().default(false).describe("Active HTTPS pour le dev server Vite (récupère les certificats du service `certificates` de `@nodefony/http`, mêmes certs que `server-https` 5152). Reco : true quand la page Nodefony est servie en HTTPS (5152) — évite le warning mixed-content. Le navigateur demandera la confiance pour 5173 si la CA root Nodefony n'est pas installée localement."),
|
|
56
|
-
viteEnv: z.record(z.string(), z.string()).default({}).describe("Variables d'environnement supplémentaires passées au child Vite. Les clés préfixées `VITE_` sont exposées au navigateur via `import.meta.env.VITE_*` (ex. `{ VITE_API_BASE: \"/api/v1\" }`). Reco prod : utiliser un `.env.production` dans le `root` Vite plutôt que cette option, pour ne pas leak de secrets dans le code Nodefony."),
|
|
51
|
+
viteEnv: z.record(z.string(), z.string()).default({}).describe("Variables d'environnement supplémentaires passées au child Vite. Les clés préfixées `VITE_` sont exposées au navigateur via `import.meta.env.VITE_*` (ex. `{ VITE_API_BASE: \"/api/v1\" }`). Reco prod : utiliser un `.env.production` dans le `root` Vite plutôt que cette option, pour ne pas leak de secrets dans le code Nodefony. Ce fichier-là est lu par Vite lui-même (variables `VITE_` publiques) — rien à voir avec le `.env` de l'application."),
|
|
57
52
|
resilience: resilienceSchema.default(() => resilienceSchema.parse({}))
|
|
58
53
|
}).describe("Configuration de @nodefony/frontend (dev server Vite + build prod).");
|
|
59
54
|
/**
|