@nodefony/frontend 10.0.0-beta.3 → 10.0.0-beta.5

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,9 +1,8 @@
1
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
1
+ // \0@oxc-project+runtime@0.155.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);
5
5
  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
6
6
  return c > 3 && r && Object.defineProperty(target, key, r), r;
7
7
  }
8
- //#endregion
9
8
  export { __decorate as default };
package/dist/index.js CHANGED
@@ -10,15 +10,14 @@ 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.153.0/helpers/esm/decorateMetadata.js";
14
- import __decorate from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
13
+ import __decorate from "./_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
15
14
  import FrontendService_default from "./nodefony/service/FrontendService.js";
16
15
  import { buildFrontendStatus, createFrontendAdminApi } from "./nodefony/src/FrontendAdminApi.js";
17
16
  import FrontendBuild from "./nodefony/command/frontend-build.js";
18
17
  import FrontendDev from "./nodefony/command/frontend-dev.js";
19
18
  import FrontendStatus from "./nodefony/command/frontend-status.js";
20
- import { Kernel, Module, services } from "nodefony";
21
- //#region index.ts
19
+ import { Module, services } from "nodefony";
20
+ // index.ts
22
21
  let Frontend = class Frontend extends Module {
23
22
  constructor(kernel) {
24
23
  super("frontend", kernel, import.meta.url, config);
@@ -57,7 +56,6 @@ let Frontend = class Frontend extends Module {
57
56
  return this;
58
57
  }
59
58
  };
60
- Frontend = __decorate([services([FrontendService_default]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Frontend);
59
+ Frontend = __decorate([services([FrontendService_default])], Frontend);
61
60
  var frontend_default = Frontend;
62
- //#endregion
63
61
  export { Frontend, FrontendError, FrontendNoEntriesError, FrontendPresetUnknownError, FrontendService_default as FrontendService, FrontendSupervisorStartError, TemplateHelper, ViteBuilder, ViteConfigGenerator, ViteProcessSupervisor, angularPreset, buildFrontendStatus, createFrontendAdminApi, frontend_default as default, defineFrontendConfig, frontendConfigJsonSchema, frontendConfigSchema, react19Preset, svelte5Preset, vanillaPreset, vue3Preset };
@@ -1,7 +1,7 @@
1
1
  import { Command } from "nodefony";
2
2
  import path from "node:path";
3
3
  import fs from "node:fs";
4
- //#region nodefony/command/frontend-build.ts
4
+ // nodefony/command/frontend-build.ts
5
5
  const options = {
6
6
  helpGroup: "FRONT ET RÉSEAU",
7
7
  showBanner: false,
@@ -20,7 +20,10 @@ const options = {
20
20
  */
21
21
  var FrontendBuild = class extends Command {
22
22
  constructor(cli) {
23
- super("frontend:build", "construit les fronts pour la production", cli, options);
23
+ super("frontend:build", "construit les fronts pour la production", cli, {
24
+ ...options,
25
+ examples: ["nodefony frontend:build", "nodefony frontend:build --force"]
26
+ });
24
27
  this.addOption("-f, --force", "rebuild even if the manifest is up-to-date");
25
28
  }
26
29
  async generate() {
@@ -64,5 +67,4 @@ var FrontendBuild = class extends Command {
64
67
  return this;
65
68
  }
66
69
  };
67
- //#endregion
68
70
  export { FrontendBuild as default };
@@ -1,5 +1,5 @@
1
1
  import { Command } from "nodefony";
2
- //#region nodefony/command/frontend-dev.ts
2
+ // nodefony/command/frontend-dev.ts
3
3
  const options = {
4
4
  helpGroup: "FRONT ET RÉSEAU",
5
5
  showBanner: false,
@@ -13,7 +13,10 @@ const options = {
13
13
  */
14
14
  var FrontendDev = class extends Command {
15
15
  constructor(cli) {
16
- super("frontend:dev", "démarre le serveur Vite à la main", cli, options);
16
+ super("frontend:dev", "démarre le serveur Vite à la main", cli, {
17
+ ...options,
18
+ examples: ["nodefony frontend:dev"]
19
+ });
17
20
  }
18
21
  async generate() {
19
22
  const svc = this.kernel?.container?.get("frontend");
@@ -27,5 +30,4 @@ var FrontendDev = class extends Command {
27
30
  return this;
28
31
  }
29
32
  };
30
- //#endregion
31
33
  export { FrontendDev as default };
@@ -1,5 +1,5 @@
1
1
  import { Command } from "nodefony";
2
- //#region nodefony/command/frontend-status.ts
2
+ // nodefony/command/frontend-status.ts
3
3
  const options = {
4
4
  helpGroup: "FRONT ET RÉSEAU",
5
5
  showBanner: false,
@@ -13,7 +13,10 @@ const options = {
13
13
  */
14
14
  var FrontendStatus = class extends Command {
15
15
  constructor(cli) {
16
- super("frontend:status", "l'état du superviseur des fronts", cli, options);
16
+ super("frontend:status", "l'état du superviseur des fronts", cli, {
17
+ ...options,
18
+ examples: ["nodefony frontend:status", "nodefony frontend:status --json"]
19
+ });
17
20
  this.addOption("-j, --json", "output as JSON");
18
21
  }
19
22
  async generate(_arg, opts) {
@@ -36,5 +39,4 @@ var FrontendStatus = class extends Command {
36
39
  return this;
37
40
  }
38
41
  };
39
- //#endregion
40
42
  export { FrontendStatus as default };
@@ -1,5 +1,5 @@
1
1
  import { z } from "zod";
2
- //#region nodefony/config/config.ts
2
+ // nodefony/config/config.ts
3
3
  /**
4
4
  * @nodefony/frontend — CONFIGURATION DU MODULE (schéma Zod = source unique).
5
5
  *
@@ -56,5 +56,4 @@ const frontendConfigSchema = z.strictObject({
56
56
  * valides par construction ; passés au `super(..., config)` du Module class.
57
57
  */
58
58
  const config = frontendConfigSchema.parse({});
59
- //#endregion
60
59
  export { config as default, frontendConfigSchema };
@@ -1,7 +1,7 @@
1
1
  import { frontendConfigSchema } from "./config.js";
2
2
  import { parseModuleConfig } from "nodefony";
3
3
  import { z } from "zod";
4
- //#region nodefony/config/defineModuleConfig.ts
4
+ // nodefony/config/defineModuleConfig.ts
5
5
  /**
6
6
  * Builder type-safe de la configuration de `@nodefony/frontend`.
7
7
  *
@@ -30,5 +30,4 @@ function defineFrontendConfig(config = {}) {
30
30
  function frontendConfigJsonSchema() {
31
31
  return z.toJSONSchema(frontendConfigSchema);
32
32
  }
33
- //#endregion
34
33
  export { defineFrontendConfig, frontendConfigJsonSchema };
@@ -5,12 +5,11 @@ import { ViteProcessSupervisor } from "./ViteProcessSupervisor.js";
5
5
  import { TemplateHelper } from "../src/template/TemplateHelper.js";
6
6
  import { devBasePath, familyPortPlan, isolationGroup } from "../src/isolationGroups.js";
7
7
  import { summarizeFrontendBoot } from "./bootSummary.js";
8
- import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
9
- import __decorate from "../../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
10
- import { FRONTEND_CHOICES, Module, Service, extend, injectable, stripTrailingSlashes } from "nodefony";
8
+ import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
9
+ import { FRONTEND_CHOICES, Service, extend, injectable, stripTrailingSlashes } from "nodefony";
11
10
  import path from "node:path";
12
11
  import fs from "node:fs";
13
- //#region nodefony/service/FrontendService.ts
12
+ // nodefony/service/FrontendService.ts
14
13
  /**
15
14
  * Normalise un préfixe public : garantit un `/` en tête et en queue.
16
15
  * `"_assets/x"` → `"/_assets/x/"`, `"/"` → `"/"`.
@@ -292,7 +291,8 @@ let FrontendService = class FrontendService extends Service {
292
291
  target: () => helper.devTarget(),
293
292
  websocket: true,
294
293
  methods: ["GET", "HEAD"],
295
- stripHeaders: ["cookie", "authorization"]
294
+ stripHeaders: ["cookie", "authorization"],
295
+ accessLog: "errors"
296
296
  });
297
297
  }
298
298
  /**
@@ -517,7 +517,6 @@ let FrontendService = class FrontendService extends Service {
517
517
  };
518
518
  }
519
519
  };
520
- FrontendService = __decorate([injectable(), __decorateMetadata("design:paramtypes", [typeof Module === "undefined" ? Object : Module])], FrontendService);
520
+ FrontendService = __decorate([injectable()], FrontendService);
521
521
  var FrontendService_default = FrontendService;
522
- //#endregion
523
522
  export { FrontendService_default as default };
@@ -1,7 +1,7 @@
1
1
  import { FrontendPresetUnknownError } from "../src/errors/FrontendError.js";
2
2
  import { createRequire } from "node:module";
3
3
  import path from "node:path";
4
- //#region nodefony/service/ViteConfigGenerator.ts
4
+ // nodefony/service/ViteConfigGenerator.ts
5
5
  /**
6
6
  * Normalise un chemin filesystem en séparateurs `/` avant sérialisation dans
7
7
  * le fichier `.mjs` généré. Le fichier généré est du JS/ESM : un backslash
@@ -117,5 +117,4 @@ ${serverBlock}
117
117
  `;
118
118
  }
119
119
  };
120
- //#endregion
121
120
  export { ViteConfigGenerator, ViteConfigGenerator as default };
@@ -7,7 +7,7 @@ import { spawn } from "node:child_process";
7
7
  import { existsSync, readFileSync, writeFileSync } from "node:fs";
8
8
  import http from "node:http";
9
9
  import https from "node:https";
10
- //#region nodefony/service/ViteProcessSupervisor.ts
10
+ // nodefony/service/ViteProcessSupervisor.ts
11
11
  /**
12
12
  * Hôte JOIGNABLE pour une adresse d'écoute : `0.0.0.0`/`::` désignent toutes
13
13
  * les interfaces, pas une destination — s'y connecter échoue sous Windows. Le
@@ -617,5 +617,4 @@ var ViteProcessSupervisor = class {
617
617
  this.childListeners = [];
618
618
  }
619
619
  };
620
- //#endregion
621
620
  export { ViteProcessSupervisor, ViteProcessSupervisor as default, browserReachableHost, isPortInUseMessage, startupTimeoutMessage };
@@ -1,4 +1,4 @@
1
- //#region nodefony/service/bootSummary.ts
1
+ // nodefony/service/bootSummary.ts
2
2
  /**
3
3
  * Résume les instances Vite pour le bilan de démarrage — fonction PURE (les
4
4
  * statuts sont lus par l'appelant), éprouvable sans lancer Vite.
@@ -40,5 +40,4 @@ function summarizeFrontendBoot(statuses) {
40
40
  notice
41
41
  };
42
42
  }
43
- //#endregion
44
43
  export { summarizeFrontendBoot };
@@ -1,7 +1,7 @@
1
1
  import { createRequire } from "node:module";
2
2
  import path from "node:path";
3
3
  import { existsSync, readFileSync } from "node:fs";
4
- //#region nodefony/src/FrontendAdminApi.ts
4
+ // nodefony/src/FrontendAdminApi.ts
5
5
  const requireFrom = createRequire(import.meta.url);
6
6
  const versionCache = /* @__PURE__ */ new Map();
7
7
  /**
@@ -109,5 +109,4 @@ function createFrontendAdminApi(service) {
109
109
  adminEndpoints: () => endpoints
110
110
  };
111
111
  }
112
- //#endregion
113
112
  export { buildFrontendStatus, createFrontendAdminApi };
@@ -5,7 +5,7 @@ import angularPreset from "../presets/angular-vite.js";
5
5
  import vanillaPreset from "../presets/vanilla-vite.js";
6
6
  import svelte5Preset from "../presets/svelte5-vite.js";
7
7
  import path from "node:path";
8
- //#region nodefony/src/builders/ViteBuilder.ts
8
+ // nodefony/src/builders/ViteBuilder.ts
9
9
  /**
10
10
  * Les paquets à dédupliquer pour un lot de préréglages — la règle, isolée.
11
11
  *
@@ -113,5 +113,4 @@ var ViteBuilder = class {
113
113
  };
114
114
  }
115
115
  };
116
- //#endregion
117
116
  export { ViteBuilder, ViteBuilder as default, resolveDedupe };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/errors/FrontendError.ts
1
+ // nodefony/src/errors/FrontendError.ts
2
2
  /**
3
3
  * Erreur de base pour @nodefony/frontend.
4
4
  *
@@ -46,5 +46,4 @@ var FrontendNoEntriesError = class extends FrontendError {
46
46
  this.name = "FrontendNoEntriesError";
47
47
  }
48
48
  };
49
- //#endregion
50
49
  export { FrontendBuildError, FrontendError, FrontendNoEntriesError, FrontendPresetUnknownError, FrontendSupervisorStartError };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/isolationGroups.ts
1
+ // nodefony/src/isolationGroups.ts
2
2
  /**
3
3
  * Famille d'isolation Vite d'un type de preset frontend.
4
4
  *
@@ -107,5 +107,4 @@ function familyPortPlan(devPort, families, portRetryAttempts) {
107
107
  });
108
108
  return plan;
109
109
  }
110
- //#endregion
111
110
  export { DEV_BASE_ROOT, PRIMARY_FAMILY, devBasePath, familyPortPlan, isolationGroup, orderFamilies };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/presets/angular-vite.ts
1
+ // nodefony/src/presets/angular-vite.ts
2
2
  /**
3
3
  * Preset Angular (17+ standalone) + Vite via `@analogjs/vite-plugin-angular`.
4
4
  *
@@ -23,5 +23,4 @@ const angularPreset = {
23
23
  return [(await import("@analogjs/vite-plugin-angular")).default()];
24
24
  }
25
25
  };
26
- //#endregion
27
26
  export { angularPreset as default };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/presets/react19-vite.ts
1
+ // nodefony/src/presets/react19-vite.ts
2
2
  /**
3
3
  * Preset React 19 + Vite.
4
4
  *
@@ -22,5 +22,4 @@ const react19Preset = {
22
22
  return [(await import("@vitejs/plugin-react")).default({ jsxRuntime: "automatic" })];
23
23
  }
24
24
  };
25
- //#endregion
26
25
  export { react19Preset as default };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/presets/svelte5-vite.ts
1
+ // nodefony/src/presets/svelte5-vite.ts
2
2
  /**
3
3
  * Preset Svelte 5 + Vite.
4
4
  *
@@ -33,5 +33,4 @@ const svelte5Preset = {
33
33
  return [mod.svelte()];
34
34
  }
35
35
  };
36
- //#endregion
37
36
  export { svelte5Preset as default };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/presets/vanilla-vite.ts
1
+ // nodefony/src/presets/vanilla-vite.ts
2
2
  /**
3
3
  * Preset vanilla — TS/JS sans framework.
4
4
  *
@@ -13,5 +13,4 @@ const vanillaPreset = {
13
13
  return [];
14
14
  }
15
15
  };
16
- //#endregion
17
16
  export { vanillaPreset as default };
@@ -1,4 +1,4 @@
1
- //#region nodefony/src/presets/vue3-vite.ts
1
+ // nodefony/src/presets/vue3-vite.ts
2
2
  /**
3
3
  * Preset Vue 3 + Vite.
4
4
  *
@@ -19,5 +19,4 @@ const vue3Preset = {
19
19
  return [(await import("@vitejs/plugin-vue")).default()];
20
20
  }
21
21
  };
22
- //#endregion
23
22
  export { vue3Preset as default };
@@ -1,8 +1,8 @@
1
1
  import { createRequire } from "node:module";
2
- import { Nodefony, PLATFORM_EVENTS, escapeRegExp } from "nodefony";
2
+ import { Nodefony, PLATFORM_EVENTS, RequestContext, escapeRegExp, isPlainObject } from "nodefony";
3
3
  import path from "node:path";
4
4
  import fs from "node:fs";
5
- //#region nodefony/src/template/TemplateHelper.ts
5
+ // nodefony/src/template/TemplateHelper.ts
6
6
  /**
7
7
  * Chemin de base de l'instance, sans `/` final : `/_vite/default` pour
8
8
  * `/_vite/default/`, vide pour `/` (doubles de test sans `base`). C'est TOUT
@@ -18,6 +18,31 @@ function basePathOf(status) {
18
18
  * (`nodefony/debugbar`). `undefined` = pas encore tenté, `null` = irrésolu.
19
19
  */
20
20
  let debugbarFile;
21
+ const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
22
+ /**
23
+ * Lit la forme d'un `manifest.json` de Vite relu sur disque : un objet dont chaque
24
+ * valeur porte au moins `file`.
25
+ *
26
+ * Une entrée mal formée est écartée — elle rendrait une balise sans fichier ; un
27
+ * document qui n'est pas un objet rend `null`, traité comme un manifeste ABSENT
28
+ * (jamais caché, donc relu au rendu suivant).
29
+ *
30
+ * @param value - le JSON parsé, de forme inconnue.
31
+ * @returns le manifeste réduit aux champs lus par le rendu, ou `null`.
32
+ */
33
+ function toViteManifest(value) {
34
+ if (!isPlainObject(value)) return null;
35
+ const manifest = {};
36
+ for (const [key, raw] of Object.entries(value)) {
37
+ if (!isPlainObject(raw) || typeof raw.file !== "string") continue;
38
+ const chunk = { file: raw.file };
39
+ if (typeof raw.isEntry === "boolean") chunk.isEntry = raw.isEntry;
40
+ if (isStringArray(raw.css)) chunk.css = raw.css;
41
+ if (isStringArray(raw.imports)) chunk.imports = raw.imports;
42
+ manifest[key] = chunk;
43
+ }
44
+ return manifest;
45
+ }
21
46
  /** Marqueur optionnel dans l'`index.html` du module où injecter les tags. */
22
47
  const FRONTEND_MARKER = "<!--nodefony:frontend-->";
23
48
  /** Échappe une string pour usage littéral dans une RegExp. */
@@ -135,7 +160,7 @@ ${tags}
135
160
  const cached = this.indexCache.get(root);
136
161
  if (cached !== void 0) return cached;
137
162
  }
138
- let html = null;
163
+ let html;
139
164
  try {
140
165
  html = fs.readFileSync(path.join(root, "index.html"), "utf8");
141
166
  } catch {
@@ -163,10 +188,10 @@ window.$RefreshSig$ = () => (type) => type;
163
188
  window.__vite_plugin_react_preamble_installed__ = true;
164
189
  <\/script>`);
165
190
  tags.push(`<script type="module"${n} src="${baseUrl}/@vite/client"><\/script>`);
166
- tags.push(`<script type="module"${n} src="${entryUrl}"><\/script>`);
167
- tags.push(this.hmrBridgeTag(baseUrl, n));
168
191
  const dbg = this.debugBarTag(baseUrl, entry.type, entryName, n);
169
192
  if (dbg) tags.push(dbg);
193
+ tags.push(`<script type="module"${n} src="${entryUrl}"><\/script>`);
194
+ tags.push(this.hmrBridgeTag(baseUrl, n));
170
195
  return tags.join("\n");
171
196
  }
172
197
  /**
@@ -210,13 +235,15 @@ try {
210
235
  if (!debugbarFile) return `<!-- @nodefony/frontend: debugbar unresolved -->`;
211
236
  const norm = debugbarFile.replace(/\\/g, "/");
212
237
  const fsUrl = `${baseUrl}${norm.startsWith("/") ? `/@fs${norm}` : `/@fs/${norm}`}`;
238
+ const requestId = RequestContext.getRequestId();
213
239
  const opts = JSON.stringify({
214
240
  frontend: {
215
241
  framework,
216
242
  name: entryName,
217
243
  viteOrigin: baseUrl
218
244
  },
219
- env: Nodefony.getKernel()?.environment ?? ""
245
+ env: Nodefony.getKernel()?.environment ?? "",
246
+ ...requestId ? { page: { requestId } } : {}
220
247
  });
221
248
  return `<script type="module"${nonceAttr}>
222
249
  import { mountDebugBar } from ${JSON.stringify(fsUrl)};
@@ -263,8 +290,8 @@ mountDebugBar(${opts});
263
290
  let parsed = null;
264
291
  for (const rel of [".vite/manifest.json", "manifest.json"]) try {
265
292
  const raw = fs.readFileSync(path.join(outDir, rel), "utf8");
266
- parsed = JSON.parse(raw);
267
- break;
293
+ parsed = toViteManifest(JSON.parse(raw));
294
+ if (parsed !== null) break;
268
295
  } catch {}
269
296
  if (parsed !== null) this.manifestCache.set(outDir, parsed);
270
297
  return parsed;
@@ -284,5 +311,4 @@ mountDebugBar(${opts});
284
311
  return out;
285
312
  }
286
313
  };
287
- //#endregion
288
314
  export { TemplateHelper, TemplateHelper as default };
package/docs/index.md CHANGED
@@ -88,19 +88,19 @@ qui remplace Vite une fois en production.
88
88
  ### La vision Nodefony — ce que ce module fait différemment
89
89
 
90
90
  **Vite est un processus système, pas une bibliothèque.** Le superviseur lance le binaire Vite avec
91
- `child_process.spawn` (`ViteProcessSupervisor.attemptSpawn()`, `ViteProcessSupervisor.ts:421`). La
91
+ `child_process.spawn` (`ViteProcessSupervisor.attemptSpawn()`, `ViteProcessSupervisor.ts#ViteProcessSupervisor.attemptSpawn`). La
92
92
  conséquence est concrète : compiler dix mille modules ne coûte **rien** à la latence de tes requêtes,
93
93
  et un plantage de Vite ne tue pas ton serveur — le superviseur le relance tout seul.
94
94
 
95
95
  **C'est Nodefony qui sert le HTML.** Beaucoup de piles séparent un serveur front (qui rend la page) et
96
96
  un serveur d'API (qui rend le JSON). Ici, la page d'entrée reste une route de ton contrôleur :
97
97
  elle traverse le pare-feu, connaît la session, reçoit son nonce CSP. Le module se contente d'y
98
- **injecter les bonnes balises** (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts:200`).
98
+ **injecter les bonnes balises** (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts#TemplateHelper.renderDevTags`).
99
99
 
100
100
  **Un seul Vite pour N modules.** Trois modules à interface ne lancent pas trois serveurs Vite : leurs
101
101
  entrées sont agrégées dans une seule instance multi-entrées. La seule exception est documentée et
102
102
  justifiée — Angular et Vue sont isolés, parce qu'un greffon voisin transformerait leurs `.ts`
103
- (`isolationGroup()`, `isolationGroups.ts:39`).
103
+ (`isolationGroup()`, `isolationGroups.ts#isolationGroup`).
104
104
 
105
105
  **Le module ne dépend ni de `@nodefony/http` ni de `@nodefony/framework`.** Tout ce dont il a besoin
106
106
  d'eux (le serveur statique, le pare-feu, les certificats, le port réellement écouté) est résolu **par
@@ -301,7 +301,7 @@ d'entrée. Ton `index.html` est **le tien** : mets-y tes polices, tes méta, tes
301
301
 
302
302
  Le marqueur `<!--nodefony:frontend-->` indique **où** injecter les balises ; sans lui, elles sont
303
303
  posées avant `</head>`. Le `<script>` d'entrée que tu vois en bas est retiré automatiquement au rendu
304
- (`TemplateHelper.injectIntoHtml()`, `TemplateHelper.ts:152`) : il n'est résolvable que par Vite quand
304
+ (`TemplateHelper.injectIntoHtml()`, `TemplateHelper.ts#TemplateHelper.injectIntoHtml`) : il n'est résolvable que par Vite quand
305
305
  Vite sert lui-même la page, ce qui n'est pas le cas ici.
306
306
 
307
307
  ### Ce qu'on observe
@@ -339,9 +339,9 @@ npx nodefony frontend:status
339
339
  ## ⚙️ Configuration
340
340
 
341
341
  Tout se déclare dans `nodefony.config.ts` via `use("@nodefony/frontend", { … })`. Le schéma Zod
342
- (`frontendConfigSchema`, `config.ts:108`) est la **source unique** des défauts : chaque `.default()`
343
- y vit, et nulle part ailleurs. Le builder `defineFrontendConfig()` (`defineModuleConfig.ts:23`) valide
344
- et gèle au démarrage ; `frontendConfigJsonSchema()` (`defineModuleConfig.ts:35`) expose le tout en
342
+ (`frontendConfigSchema`, `config.ts#frontendConfigSchema`) est la **source unique** des défauts : chaque `.default()`
343
+ y vit, et nulle part ailleurs. Le builder `defineFrontendConfig()` (`defineModuleConfig.ts#defineFrontendConfig`) valide
344
+ et gèle au démarrage ; `frontendConfigJsonSchema()` (`defineModuleConfig.ts#frontendConfigJsonSchema`) expose le tout en
345
345
  JSON Schema pour l'écran de configuration de Studio.
346
346
 
347
347
  > [!NOTE]
@@ -375,7 +375,7 @@ JSON Schema pour l'écran de configuration de Studio.
375
375
 
376
376
  ### La résilience du superviseur
377
377
 
378
- Sous-section `resilience` (`resilienceSchema`, `config.ts:36`). Tout est optionnel ; les défauts
378
+ Sous-section `resilience` (`resilienceSchema`, `config.ts#resilienceSchema`). Tout est optionnel ; les défauts
379
379
  s'appliquent même si tu omets la section entière.
380
380
 
381
381
  | Option | Défaut | Effet |
@@ -452,7 +452,7 @@ son existence.
452
452
  ### Qui décide, et comment
453
453
 
454
454
  Le module qui embarque une interface expose une molette `ui` avec trois positions, résolue au
455
- démarrage par `resolveUiDelivery()` (`prebuiltUi.ts:48`, dans `@nodefony/http`) :
455
+ démarrage par `resolveUiDelivery()` (`prebuiltUi.ts#resolveUiDelivery`, dans `@nodefony/http`) :
456
456
 
457
457
  | Molette | Comportement |
458
458
  | -------- | ----------------------------------------------------------------------------------------------------------------- |
@@ -466,14 +466,14 @@ actionnable (« le paquet a-t-il bien construit son interface à la publication
466
466
 
467
467
  ### Ce que fait chaque mode
468
468
 
469
- | Aspect | Mode `vite` | Mode `static` |
470
- | -------------------- | --------------------------------------------- | ---------------------------------------------------------- |
471
- | D'où viennent les JS | serveur Vite, port dédié | dossier `dist/` servi par le serveur statique |
472
- | Rechargement à chaud | oui | non |
473
- | `registerEntry` | appelé — le module est visible du superviseur | **jamais appelé** — le module est invisible du superviseur |
474
- | Dépendance à Vite | oui (`peerDependency`) | **aucune** |
475
- | Rendu de la page | `renderDocument` / `renderTags` | `PrebuiltUi.renderIndex()` (`prebuiltUi.ts:196`) |
476
- | Nonce CSP | posé sur chaque balise injectée | posé par remplacement sur chaque `<script>` de l'index |
469
+ | Aspect | Mode `vite` | Mode `static` |
470
+ | -------------------- | --------------------------------------------- | ------------------------------------------------------------------- |
471
+ | D'où viennent les JS | serveur Vite, port dédié | dossier `dist/` servi par le serveur statique |
472
+ | Rechargement à chaud | oui | non |
473
+ | `registerEntry` | appelé — le module est visible du superviseur | **jamais appelé** — le module est invisible du superviseur |
474
+ | Dépendance à Vite | oui (`peerDependency`) | **aucune** |
475
+ | Rendu de la page | `renderDocument` / `renderTags` | `PrebuiltUi.renderIndex()` (`prebuiltUi.ts#PrebuiltUi.renderIndex`) |
476
+ | Nonce CSP | posé sur chaque balise injectée | posé par remplacement sur chaque `<script>` de l'index |
477
477
 
478
478
  > [!IMPORTANT]
479
479
  > **Un module en mode `static` n'apparaît pas dans `listEntries()`.** C'est logique une fois le
@@ -512,21 +512,21 @@ sequenceDiagram
512
512
  ```
513
513
 
514
514
  **Pourquoi `onServersReady` et pas `onReady`.** Vite démarre une fois les serveurs Nodefony en
515
- écoute (`FrontendService.init()`, `FrontendService.ts:142`) : rien ne peut lui être relayé avant, le relais `/_vite/` vivant dans leur
515
+ écoute (`FrontendService.init()`, `FrontendService.ts#FrontendService.init`) : rien ne peut lui être relayé avant, le relais `/_vite/` vivant dans leur
516
516
  pipeline, et le lancer ensuite ne retarde pas l'ouverture des ports — Vite compile pendant que
517
517
  Nodefony sert déjà.
518
518
 
519
519
  ### Les pièces
520
520
 
521
- | Pièce | Rôle | Ancre |
522
- | ----------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------- |
523
- | `FrontendService` | l'orchestrateur : entrées, familles, cycle de vie, rendu | `FrontendService.ts:70` |
524
- | `ViteProcessSupervisor` | lance, surveille, relance et arrête **un** processus Vite | `ViteProcessSupervisor.ts:236` |
525
- | `ViteConfigGenerator` | écrit la configuration Vite (fonction pure, testée seule) | `ViteConfigGenerator.toMjs()` (`ViteConfigGenerator.ts:63`) |
526
- | `ViteBuilder` | construit l'objet de configuration Vite pour le build en processus | `ViteBuilder.buildViteConfig()` (`ViteBuilder.ts:95`) |
527
- | `TemplateHelper` | produit les balises (dev) ou lit le manifeste (prod) | `TemplateHelper.ts:36` |
528
- | `isolationGroups` | à quelle famille appartient un preset, et sur quel bloc de ports | `isolationGroup()` (`isolationGroups.ts:39`) |
529
- | `FrontendAdminApi` | la vue sûre de l'état, pour Studio | `buildFrontendStatus()` (`FrontendAdminApi.ts:147`) |
521
+ | Pièce | Rôle | Ancre |
522
+ | ----------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
523
+ | `FrontendService` | l'orchestrateur : entrées, familles, cycle de vie, rendu | `FrontendService.ts#FrontendService` |
524
+ | `ViteProcessSupervisor` | lance, surveille, relance et arrête **un** processus Vite | `ViteProcessSupervisor.ts#ViteProcessSupervisor` |
525
+ | `ViteConfigGenerator` | écrit la configuration Vite (fonction pure, testée seule) | `ViteConfigGenerator.toMjs()` (`ViteConfigGenerator.ts#ViteConfigGenerator.toMjs`) |
526
+ | `ViteBuilder` | construit l'objet de configuration Vite pour le build en processus | `ViteBuilder.buildViteConfig()` (`ViteBuilder.ts#ViteBuilder.buildViteConfig`) |
527
+ | `TemplateHelper` | produit les balises (dev) ou lit le manifeste (prod) | `TemplateHelper.ts#TemplateHelper` |
528
+ | `isolationGroups` | à quelle famille appartient un preset, et sur quel bloc de ports | `isolationGroup()` (`isolationGroups.ts#isolationGroup`) |
529
+ | `FrontendAdminApi` | la vue sûre de l'état, pour Studio | `buildFrontendStatus()` (`FrontendAdminApi.ts#buildFrontendStatus`) |
530
530
 
531
531
  ### Une configuration Vite écrite, pas passée
532
532
 
@@ -539,7 +539,7 @@ il importe lui-même les greffons dont les presets détectés ont besoin.
539
539
 
540
540
  - une **entrée par bundle** (`input`), d'où le multi-modules dans une seule instance ;
541
541
  - la `base` sur le **chemin réservé de la famille** (`/_vite/<famille>/`, `devBasePath()`,
542
- `isolationGroups.ts:75`) — chaque URL que Vite écrit dans un module retombe ainsi sous le préfixe
542
+ `isolationGroups.ts#devBasePath`) — chaque URL que Vite écrit dans un module retombe ainsi sous le préfixe
543
543
  que Nodefony relaie, sur l'origine de la page ;
544
544
  - `strictPort` : c'est le superviseur qui choisit le port, et le relais vise ce port. Un Vite qui
545
545
  glisserait de lui-même servirait ailleurs que là où le relais l'attend ;
@@ -555,10 +555,10 @@ il importe lui-même les greffons dont les presets détectés ont besoin.
555
555
 
556
556
  Au démarrage de chaque famille, le service monte son chemin réservé sur le
557
557
  [proxy inverse](../../http/docs/reverse-proxy.md) de `@nodefony/http`
558
- (`FrontendService.mountDevProxy()`, `FrontendService.ts:486`). Toute requête sous `/_vite/<famille>/`
558
+ (`FrontendService.mountDevProxy()`, `FrontendService.ts#FrontendService.mountDevProxy`). Toute requête sous `/_vite/<famille>/`
559
559
  — module, style, image importée, et l'upgrade WebSocket du rechargement à chaud — est alors relayée
560
560
  à Vite, sur la boucle locale ; la cible est le port **que Vite sert vraiment**
561
- (`TemplateHelper.devTarget()`, `TemplateHelper.ts:91`), jamais un port seulement retenu par une
561
+ (`TemplateHelper.devTarget()`, `TemplateHelper.ts#TemplateHelper.devTarget`), jamais un port seulement retenu par une
562
562
  instance tombée, qu'une autre application aurait pu reprendre.
563
563
 
564
564
  Ce que ça change pour toi :
@@ -581,29 +581,29 @@ qui finit par `.ts` (`Comp.vue?vue&type=script&lang.ts`) : le greffon React y in
581
581
  `$RefreshSig$()`, que rien ne définit hors d'une page React, et le composant ne se monte plus. Des
582
582
  extensions différentes n'y changent rien, et l'option `exclude` du greffon React non plus.
583
583
 
584
- D'où le regroupement par **famille** (`isolationGroup()`, `isolationGroups.ts:39`) : `angular` et
584
+ D'où le regroupement par **famille** (`isolationGroup()`, `isolationGroups.ts#isolationGroup`) : `angular` et
585
585
  `vue` ont chacune la leur, tout le reste partage `default`. Chaque famille obtient un **bloc de ports disjoint**
586
- (`familyPortPlan()`, `isolationGroups.ts:112`) de taille `portRetryAttempts + 1` : ainsi, une instance
586
+ (`familyPortPlan()`, `isolationGroups.ts#familyPortPlan`) de taille `portRetryAttempts + 1` : ainsi, une instance
587
587
  qui glisse de port sur conflit ne peut jamais empiéter sur le bloc d'une autre. La famille principale
588
- garde le port habituel (`PRIMARY_FAMILY`, `isolationGroups.ts:84`).
588
+ garde le port habituel (`PRIMARY_FAMILY`, `isolationGroups.ts#PRIMARY_FAMILY`).
589
589
 
590
590
  **Les familles démarrent indépendamment.** Si Angular échoue, React continue de fonctionner : le
591
591
  démarrage n'échoue que si **aucune** famille n'a pu démarrer (`FrontendService.startDev()`,
592
- `FrontendService.ts:314`).
592
+ `FrontendService.ts#FrontendService.startDev`).
593
593
 
594
594
  ### Résilience — ce qui se passe quand Vite tombe
595
595
 
596
596
  Le superviseur est écrit pour survivre à un poste de développement réel, où les ports sont occupés et
597
597
  les processus meurent.
598
598
 
599
- | Situation | Réponse |
600
- | -------------------------- | ----------------------------------------------------------------------------------------------------- |
601
- | Port occupé au lancement | essai sur le port suivant, jusqu'à `portRetryAttempts` (`ViteProcessSupervisor.ts:301`) |
602
- | Vite plante | relance avec délai exponentiel plafonné (`scheduleRestart()`, `ViteProcessSupervisor.ts:704`) |
603
- | Vite ne répond plus (gelé) | sonde périodique ; après N échecs, Vite est tué pour être relancé (`ViteProcessSupervisor.ts:787`) |
604
- | Deux `start()` concurrents | la promesse en cours est partagée — jamais deux processus |
605
- | Ctrl+C au terminal | le signal marque un arrêt **voulu** : pas de relance (`markShutdown`, `ViteProcessSupervisor.ts:272`) |
606
- | Arrêt du kernel | `SIGINT`, puis `SIGKILL` après 3 s — aucun zombie ne bloque le port (`ViteProcessSupervisor.ts:888`) |
599
+ | Situation | Réponse |
600
+ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
601
+ | Port occupé au lancement | essai sur le port suivant, jusqu'à `portRetryAttempts` (`ViteProcessSupervisor.ts#ViteProcessSupervisor.constructor`) |
602
+ | Vite plante | relance avec délai exponentiel plafonné (`scheduleRestart()`, `ViteProcessSupervisor.ts#ViteProcessSupervisor.scheduleRestart`) |
603
+ | Vite ne répond plus (gelé) | sonde périodique ; après N échecs, Vite est tué pour être relancé (`ViteProcessSupervisor.ts#ViteProcessSupervisor.startHealthCheck`) |
604
+ | Deux `start()` concurrents | la promesse en cours est partagée — jamais deux processus |
605
+ | Ctrl+C au terminal | le signal marque un arrêt **voulu** : pas de relance (`markShutdown`, `ViteProcessSupervisor.ts#ViteProcessSupervisor.markShutdown`) |
606
+ | Arrêt du kernel | `SIGINT`, puis `SIGKILL` après 3 s — aucun zombie ne bloque le port (`ViteProcessSupervisor.ts#ViteProcessSupervisor.doStop`) |
607
607
 
608
608
  Deux subtilités valent d'être connues, parce qu'elles expliquent des comportements sinon
609
609
  incompréhensibles :
@@ -612,7 +612,7 @@ incompréhensibles :
612
612
  marquage du signal reçu par le processus serveur, un simple Ctrl+C ferait apparaître un
613
613
  « redémarrage échoué » en erreur, sur un arrêt parfaitement normal.
614
614
  - **La détection d'un port occupé est écrite à un seul endroit** (`isPortInUseMessage()`,
615
- `ViteProcessSupervisor.ts:185`), et elle reconnaît un conflit **FATAL**, pas la simple présence de
615
+ `ViteProcessSupervisor.ts#isPortInUseMessage`), et elle reconnaît un conflit **FATAL**, pas la simple présence de
616
616
  « in use ». Vite écrit trois textes qui contiennent ces mots, et un seul signifie qu'il a échoué :
617
617
  « Port X is **already** in use » (il meurt — le seul cas où reprendre sur un autre port a un sens),
618
618
  « Port X is in use, **trying another one…** » (il se décale lui-même) et « Port X is in use **on a
@@ -621,7 +621,7 @@ incompréhensibles :
621
621
  repayant l'attente de démarrage à chaque essai.
622
622
 
623
623
  Les écouteurs attachés au processus enfant sont suivis puis retirés à chaque mort
624
- (`cleanupChildListeners()`, `ViteProcessSupervisor.ts:959`) : sans cela, les relances successives les
624
+ (`cleanupChildListeners()`, `ViteProcessSupervisor.ts#ViteProcessSupervisor.cleanupChildListeners`) : sans cela, les relances successives les
625
625
  accumuleraient jusqu'à l'avertissement de fuite.
626
626
 
627
627
  ## 🧰 API publique
@@ -632,9 +632,9 @@ et dans les types du paquet — jamais recopiées ici, où elles se périmeraien
632
632
 
633
633
  ### `registerEntry` — la déclaration d'une interface
634
634
 
635
- `FrontendService.registerEntry()` (`FrontendService.ts:228`) est appelée par le module consommateur,
635
+ `FrontendService.registerEntry()` (`FrontendService.ts#FrontendService.registerEntry`) est appelée par le module consommateur,
636
636
  dans son `onKernelBoot()`. Elle résout les chemins relatifs, calcule le préfixe public et renvoie
637
- l'entrée résolue (`IResolvedFrontendEntry`, `IFrontBuilder.ts:33`).
637
+ l'entrée résolue (`IResolvedFrontendEntry`, `IFrontBuilder.ts#IResolvedFrontendEntry`).
638
638
 
639
639
  | Champ | Requis | Défaut | Rôle |
640
640
  | ------------ | ------ | ------------------ | --------------------------------------------------------------- |
@@ -670,12 +670,12 @@ const tags = frontend.renderTags("shop", context.cspNonce);
670
670
  const html = frontend.renderDocument("shop", context.cspNonce);
671
671
  ```
672
672
 
673
- `renderDocument` (`FrontendService.ts:753`) lit l'`index.html` **de ton module**, retire le `<script>`
673
+ `renderDocument` (`FrontendService.ts#FrontendService.renderDocument`) lit l'`index.html` **de ton module**, retire le `<script>`
674
674
  d'entrée source, injecte les balises au marqueur (ou avant `</head>`), et renvoie le document.
675
675
  Pas d'`index.html` ? Une coquille minimale est générée. En production, l'index est mis en cache ; en
676
676
  développement il est relu à chaque appel, pour que tes modifications de la coquille apparaissent.
677
677
 
678
- Ce qui est injecté en développement (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts:200`) :
678
+ Ce qui est injecté en développement (`TemplateHelper.renderDevTags()`, `TemplateHelper.ts#TemplateHelper.renderDevTags`) :
679
679
 
680
680
  1. le **préambule React Fast Refresh** pour les entrées `react19` — sans lui, `@vitejs/plugin-react`
681
681
  refuse de démarrer ;
@@ -683,17 +683,44 @@ Ce qui est injecté en développement (`TemplateHelper.renderDevTags()`, `Templa
683
683
  3. ton entrée, servie par son **chemin absolu** (`/@fs/…`) plutôt que relatif — c'est ce qui permet à
684
684
  deux modules d'avoir chacun leur `frontend/src/main.tsx` sans collision ;
685
685
  4. un pont qui relaie les événements de rechargement vers la barre de débogage, **sans ouvrir de
686
- seconde connexion** (`hmrBridgeTag()`, `TemplateHelper.ts:277`) ;
686
+ seconde connexion** (`hmrBridgeTag()`, `TemplateHelper.ts#TemplateHelper.hmrBridgeTag`) ;
687
687
  5. la barre de débogage elle-même, résolue une fois et servie via Vite (`debugBarTag()`,
688
- `TemplateHelper.ts:303`).
688
+ `TemplateHelper.ts#TemplateHelper.debugBarTag`).
689
689
 
690
690
  Quand Vite n'est pas prêt, le rendu ne lève **jamais** : il renvoie un commentaire HTML disant
691
691
  l'état. Une page dégradée reste une page.
692
692
 
693
+ ### Une route profonde, et la touche F5
694
+
695
+ Ton application monopage navigue côté navigateur : `/commandes/42` n'est qu'un état de l'écran. Mais
696
+ au premier chargement — un lien partagé, un F5 —, c'est le **serveur** qui reçoit ce chemin, et sans
697
+ route qui rende la page il répond 404. Le contrôleur de la page doit donc servir aussi les chemins
698
+ profonds, par une route de **repli** :
699
+
700
+ ```ts ignore
701
+ // Dans le contrôleur qui rend la page (AppController d'une application générée)
702
+ @route("route-app-commandes", {
703
+ path: "/commandes/*",
704
+ method: "GET",
705
+ fallback: true,
706
+ })
707
+ renderDeep(): unknown {
708
+ return this.renderApp();
709
+ }
710
+ ```
711
+
712
+ `fallback: true` range la route **après toutes les autres** (`Route.ts#RouteOptions.fallback`) : une
713
+ route d'API de même forme, déclarée par n'importe quel module, garde la priorité — voir
714
+ [l'ordre de résolution](../../framework/docs/routing.md#-ordre-de-résolution--trois-situations).
715
+ Deux détails : `/commandes/*` n'attrape pas `/commandes` lui-même (la barre oblique est requise),
716
+ qui demande sa propre route ; et un repli à la **racine** (`/*`) transformerait toute faute de
717
+ frappe — une URL d'API, un fichier absent — en page HTML servie en 200. Borne le repli aux
718
+ préfixes de ton application.
719
+
693
720
  ### Les helpers de vue
694
721
 
695
722
  Si tu rends une vue Eta plutôt qu'une chaîne, trois helpers sont déjà dans tes variables locales
696
- (`Controller.withFrontendLocals()`, `Controller.ts:594`) — inspirés des helpers d'assets de Symfony :
723
+ (`Controller.withFrontendLocals()`, `Controller.ts#Controller.withFrontendLocals`) — inspirés des helpers d'assets de Symfony :
697
724
 
698
725
  ```html
699
726
  <%~ frontendDocument("shop") %>
@@ -718,21 +745,21 @@ Dans une application générée par `nodefony create app`, tu n'as pas à y pens
718
745
  **`npm run build` construit l'application entière** — le backend (rolldown) puis le front (il
719
746
  chaîne `nodefony frontend:build`). Un seul geste avant `npm start` ou dans un pipeline.
720
747
 
721
- `FrontendService.build()` (`FrontendService.ts:634`) appelle Vite **entrée par entrée**, et non une
748
+ `FrontendService.build()` (`FrontendService.ts#FrontendService.build`) appelle Vite **entrée par entrée**, et non une
722
749
  fois pour toutes. Ce n'est pas un détail : chaque bundle a sa racine, son dossier de sortie, sa base
723
750
  et son manifeste — c'est ce qui rend le multi-modules possible et ce qui isole Angular.
724
751
 
725
752
  Quatre comportements à connaître :
726
753
 
727
754
  - **Idempotent.** Une entrée dont le manifeste est plus récent que ses sources est ignorée
728
- (`isBuildFresh()`, `FrontendService.ts:704`) — le scan est borné au dossier front et saute
755
+ (`isBuildFresh()`, `FrontendService.ts#FrontendService.isBuildFresh`) — le scan est borné au dossier front et saute
729
756
  `node_modules`. Relancer un déploiement ne recompile pas tout.
730
757
  - **Les échecs sont collectés, pas propagés.** Un bundle en échec n'arrête pas les autres ; la
731
758
  commande passe le code de sortie à `1` s'il en reste un — de quoi casser un pipeline sans masquer
732
759
  les autres résultats.
733
760
  - **Le résultat est un bilan** : construits / ignorés / en échec, journalisé et renvoyé.
734
761
  - **Un démarrage en production sans build se répare — ou se dénonce.** `setupProd()`
735
- (`FrontendService.ts:525`) vérifie le manifeste de chaque entrée AVANT de monter les statics.
762
+ (`FrontendService.ts#FrontendService.setupProd`) vérifie le manifeste de chaque entrée AVANT de monter les statics.
736
763
  Manifeste absent et Vite installé (poste de développement, devDependencies présentes) : le build
737
764
  tourne **une fois au démarrage**, annoncé en WARNING — fini l'écran blanc après un
738
765
  `nodefony production --detach` lancé trop tôt. Manifeste absent et Vite introuvable (image de
@@ -756,7 +783,7 @@ page. Les trois restent alignés par construction — impossible d'en changer un
756
783
  deux autres.
757
784
 
758
785
  Défaut : `/_assets/<name>/`, normalisé avec ses barres obliques
759
- (`normalizePublicPath()`, `FrontendService.ts:70`). Chaque bundle a donc son espace, sans collision
786
+ (`normalizePublicPath()`, `FrontendService.ts#normalizePublicPath`). Chaque bundle a donc son espace, sans collision
760
787
  entre modules.
761
788
 
762
789
  `assetBaseUrl` ajoute une couche : la base d'un CDN. Renseignée, elle préfixe la `base` du build et
@@ -768,18 +795,18 @@ use("@nodefony/frontend", { assetBaseUrl: "https://cdn.example.com" });
768
795
  // → <script src="https://cdn.example.com/_assets/shop/main-a1b2c3.js">
769
796
  ```
770
797
 
771
- En production, `setupProd()` (`FrontendService.ts:525`) monte chaque dossier de sortie sur son
798
+ En production, `setupProd()` (`FrontendService.ts#FrontendService.setupProd`) monte chaque dossier de sortie sur son
772
799
  `publicPath` via le serveur statique — résolu **par nom**, jamais par import, pour ne pas créer de
773
800
  cycle. Si ce service est absent (proxy frontal, CDN devant), un avertissement le dit et rien n'est
774
801
  monté : c'est un déploiement valide, pas une panne.
775
802
 
776
803
  ### Ce qui est servi en production
777
804
 
778
- `renderProdTags()` (`TemplateHelper.ts:336`) lit `manifest.json` — la carte produite par Vite — et
805
+ `renderProdTags()` (`TemplateHelper.ts#TemplateHelper.renderProdTags`) lit `manifest.json` — la carte produite par Vite — et
779
806
  émet, dans cet ordre : les feuilles de style d'abord (pour éviter le flash de contenu non stylé), les
780
807
  préchargements des morceaux partagés, puis le script d'entrée. Le manifeste est lu **une fois par
781
808
  dossier de sortie** et mis en cache : aucune lecture disque par requête. Le CSS est collecté
782
- récursivement à travers les imports (`collectCss()`, `TemplateHelper.ts:410`), sans quoi le style
809
+ récursivement à travers les imports (`collectCss()`, `TemplateHelper.ts#TemplateHelper.collectCss`), sans quoi le style
783
810
  d'un morceau partagé manquerait sur certaines pages.
784
811
 
785
812
  Manifeste absent ? Un commentaire HTML le dit, avec la commande à lancer. Pas d'exception, pas de
@@ -787,11 +814,11 @@ page blanche muette.
787
814
 
788
815
  ## 🧩 Extension
789
816
 
790
- **Ajouter un framework UI** revient à écrire un preset (`IFrontPreset`, `IFrontPreset.ts:15`) : son
817
+ **Ajouter un framework UI** revient à écrire un preset (`IFrontPreset`, `IFrontPreset.ts#IFrontPreset`) : son
791
818
  identifiant, ses extensions, ses dépendances à pré-empaqueter, et une fonction qui construit ses
792
- greffons Vite. Les cinq presets fournis sont les modèles à copier — React (`react19-vite.ts:9`),
793
- Vue (`vue3-vite.ts:11`), Angular (`angular-vite.ts:15`), Svelte (`svelte5-vite.ts:13`),
794
- vanilla (`vanilla-vite.ts:9`). Tous
819
+ greffons Vite. Les cinq presets fournis sont les modèles à copier — React (`react19-vite.ts#react19Preset`),
820
+ Vue (`vue3-vite.ts#vue3Preset`), Angular (`angular-vite.ts#angularPreset`), Svelte (`svelte5-vite.ts#svelte5Preset`),
821
+ vanilla (`vanilla-vite.ts#vanillaPreset`). Tous
795
822
  importent leur greffon **paresseusement** : un preset non utilisé ne coûte ni installation, ni
796
823
  chargement.
797
824
 
@@ -799,12 +826,12 @@ Deux points d'attention avant de se lancer :
799
826
 
800
827
  - le preset alimente le build en processus (`ViteBuilder`), mais la configuration du **serveur de
801
828
  développement** est écrite par le générateur, qui possède sa propre correspondance type → greffon
802
- (`ViteConfigGenerator.toMjs()`, `ViteConfigGenerator.ts:63`). Un nouveau type doit être ajouté aux
803
- **deux** endroits, sinon il lève `FrontendPresetUnknownError` (`FrontendError.ts:19`) ;
829
+ (`ViteConfigGenerator.toMjs()`, `ViteConfigGenerator.ts#ViteConfigGenerator.toMjs`). Un nouveau type doit être ajouté aux
830
+ **deux** endroits, sinon il lève `FrontendPresetUnknownError` (`FrontendError.ts#FrontendPresetUnknownError`) ;
804
831
  - si le nouveau framework transforme des fichiers qui ne lui appartiennent pas, il lui faut sa propre
805
832
  famille d'isolation — c'est la leçon d'Angular.
806
833
 
807
- **Remplacer le superviseur** est prévu par le contrat `IViteSupervisor` (`IViteSupervisor.ts:64`) :
834
+ **Remplacer le superviseur** est prévu par le contrat `IViteSupervisor` (`IViteSupervisor.ts#IViteSupervisor`) :
808
835
  `start`, `stop`, `status`. C'est le seul point d'isolement entre « Vite dans un processus séparé » et
809
836
  toute autre stratégie.
810
837
 
@@ -817,10 +844,10 @@ socket viennent de l'origine de la page. La politique n'a donc **aucune origine
817
844
 
818
845
  Le développement a pourtant deux besoins que la politique stricte refuse. Plutôt que de l'affaiblir,
819
846
  le service les **compose** : une fois Vite prêt, il déclare son fragment au pare-feu
820
- (`#registerCsp()`, `FrontendService.ts:782`), qui émet **un seul** en-tête, fragment fusionné et
847
+ (`#registerCsp()`, `FrontendService.ts#FrontendService.#registerCsp`), qui émet **un seul** en-tête, fragment fusionné et
821
848
  nonce par requête. À l'arrêt, le fragment est retiré et la politique redevient stricte.
822
849
 
823
- Le fragment (`#viteCspFragment()`, `FrontendService.ts:804`) mérite deux explications, parce
850
+ Le fragment (`#viteCspFragment()`, `FrontendService.ts#FrontendService.#viteCspFragment`) mérite deux explications, parce
824
851
  qu'elles piègent tout le monde :
825
852
 
826
853
  - **`'self'` est répété dans chaque directive.** `connect-src`, `style-src`, `img-src` et `font-src`
@@ -839,7 +866,7 @@ Aucune origine n'y figure : le fragment est le même quel que soit le nom par le
839
866
  > fuirait jusqu'à un déploiement.
840
867
 
841
868
  Deux garde-fous complètent le tableau : le producteur de données pour Studio expose une vue **sans
842
- chemins de fichiers absolus** (`IViteInstanceView`, `FrontendAdminApi.ts:80`), et le serveur de
869
+ chemins de fichiers absolus** (`IViteInstanceView`, `FrontendAdminApi.ts#IViteInstanceView`), et le serveur de
843
870
  développement n'autorise l'accès disque qu'aux racines explicitement listées.
844
871
 
845
872
  ## ⚡ Performance et mémoire
@@ -855,7 +882,7 @@ Sur le chemin chaud du rendu, trois précautions :
855
882
  - le **manifeste** est lu une fois par dossier de sortie, jamais par requête ;
856
883
  - l'**`index.html`** est mis en cache en production (relu en développement, où la fraîcheur prime) ;
857
884
  - les **écouteurs** du processus enfant sont suivis et retirés à chaque mort
858
- (`trackListener()`, `ViteProcessSupervisor.ts:949`) — sans quoi les relances les accumuleraient.
885
+ (`trackListener()`, `ViteProcessSupervisor.ts#ViteProcessSupervisor.trackListener`) — sans quoi les relances les accumuleraient.
859
886
 
860
887
  La sonde de vie coûte une requête HTTP toutes les trente secondes par famille. Elle est désactivable
861
888
  (`healthCheckIntervalMs: 0`) si ce budget te gêne, au prix de la détection d'un Vite gelé.
@@ -866,7 +893,7 @@ En ligne de commande, `nodefony frontend:status` donne l'état, le point d'écou
866
893
  entrées servies ; `-j` produit le même contenu en JSON, exploitable par un script.
867
894
 
868
895
  Côté data plane, le module enregistre son producteur au démarrage
869
- (`createFrontendAdminApi()`, `FrontendAdminApi.ts:173`) :
896
+ (`createFrontendAdminApi()`, `FrontendAdminApi.ts#createFrontendAdminApi`) :
870
897
 
871
898
  | Route | Contenu |
872
899
  | --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
@@ -901,8 +928,12 @@ apparaisse avant le « prêt ».
901
928
  | `421 Misdirected Request` depuis un autre appareil | `domainCheck` actif, et cet hôte absent de `trustedHosts` | ajouter l'IP ou le nom à `trustedHosts` du module HTTP |
902
929
  | Page blanche sur un appareil ancien (TV, vieux Safari) | le client cible ES2022 | `@vitejs/plugin-legacy` côté application — voir [Compatibilité](../../../../../docs/guides/compatibilite.md#navigateurs--la-cible-du-client) |
903
930
  | `Refused to load the script` (politique de sécurité) | page rendue avant que Vite soit prêt : le fragment de développement n'est pas encore déclaré | recharger une fois Vite prêt ; vérifier que le nonce est bien propagé |
904
- | Commentaire `prod manifest missing` dans la page | les bundles n'ont pas été construits, et Vite n'était pas là pour le faire au démarrage | `npm run build` (ou `npx nodefony frontend:build`) puis **recharge la page** — l'absence de manifeste n'est jamais mise en cache (`loadManifest()`, `TemplateHelper.ts:386`), le serveur voit le build sans redémarrer |
931
+ | 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#TemplateHelper.loadManifest`), le serveur voit le build sans redémarrer |
905
932
  | 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` |
933
+ | Après un `frontend:build` lancé serveur démarré, la page demande des fichiers en 404 | un manifeste TROUVÉ est gardé pour toute la vie du processus (`loadManifest()`, `TemplateHelper.ts#TemplateHelper.loadManifest`), et le build vide le dossier de sortie : la page désigne des fichiers effacés | redémarrer après tout build en production ; en déploiement réel, le build se fait à l'image, avant le démarrage |
934
+ | Après un redéploiement, un onglet resté ouvert casse au changement d'écran (`Failed to fetch dynamically imported module`) | il demande les morceaux de la génération précédente, dont les noms hachés n'existent plus | écouter l'événement `vite:preloadError` et recharger la page **une** fois, avec une garde anti-boucle — ce que fait la console d'administration (`staleChunk.ts#lazyRoute`) |
935
+ | Un import hors du dossier front est refusé par Vite (403) | le serveur de développement n'ouvre que le dossier de l'application, la racine de chaque entrée et la barre de débogage (`ViteConfigGenerator.toMjs()`, `ViteConfigGenerator.ts#ViteConfigGenerator.toMjs`) | placer la ressource sous l'une de ces racines |
936
+ | F5 sur une page profonde de l'application rend 404 | aucune route serveur ne rend la page pour ce chemin | une route de repli — voir [Une route profonde, et la touche F5](#une-route-profonde-et-la-touche-f5) |
906
937
  | 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 |
907
938
  | Modifications du front sans effet | `vite.config.generated.mjs` édité à la main | ne jamais l'éditer : il est réécrit à chaque démarrage |
908
939
  | Angular recharge la page entière au lieu du composant | son greffon ne fait pas de remplacement à chaud | attendu — c'est le comportement du greffon Angular |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodefony/frontend",
3
- "version": "10.0.0-beta.3",
3
+ "version": "10.0.0-beta.5",
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",
@@ -36,24 +36,24 @@
36
36
  "esm"
37
37
  ],
38
38
  "peerDependencies": {
39
- "@nodefony/framework": "^10.0.0-beta.3",
40
- "@nodefony/http": "^10.0.0-beta.3",
41
- "nodefony": "^10.0.0-beta.3",
39
+ "@nodefony/framework": "^10.0.0-beta.5",
40
+ "@nodefony/http": "^10.0.0-beta.5",
41
+ "nodefony": "^10.0.0-beta.5",
42
42
  "zod": "^4.6.7"
43
43
  },
44
44
  "devDependencies": {
45
- "@nodefony/framework": "^10.0.0-beta.3",
46
- "@nodefony/http": "^10.0.0-beta.3",
45
+ "@nodefony/framework": "^10.0.0-beta.5",
46
+ "@nodefony/http": "^10.0.0-beta.5",
47
47
  "@types/chai": "5.2.3",
48
48
  "@types/node": "26.6.5",
49
- "@vitest/coverage-v8": "5.0.4",
50
- "nodefony": "^10.0.0-beta.3",
51
- "vite": "8.3.4",
52
- "vitest": "5.0.4"
49
+ "@vitest/coverage-v8": "5.0.5",
50
+ "nodefony": "^10.0.0-beta.5",
51
+ "vite": "8.3.5",
52
+ "vitest": "5.0.5"
53
53
  },
54
54
  "private": false,
55
55
  "engines": {
56
- "node": ">=24.0.0"
56
+ "node": ">=24.14.0"
57
57
  },
58
58
  "license": "Apache-2.0",
59
59
  "dependencies": {
@@ -1,6 +0,0 @@
1
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateMetadata.js
2
- function __decorateMetadata(k, v) {
3
- if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
4
- }
5
- //#endregion
6
- export { __decorateMetadata as default };