---
title: "Référence d'API — @nodefony/frontend"
source: docs/api/frontend.md
url: https://nodefony.github.io/nodefony-core/docs/api/frontend/
---


[Documentation](../../) › [Référence d'API](../) › `@nodefony/frontend`

> Générée depuis les déclarations de types publiées de `@nodefony/frontend` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

## `@nodefony/frontend`

`import { … } from "@nodefony/frontend"` — 34 symboles.

### Classes (11)

#### `Frontend`

```ts
class Frontend extends Module<IFrontendConfig>
```

- `constructor(kernel: Kernel)`
- `configSchema(): unknown` — JSON Schema de la config frontend → data plane admin (config riche Studio).
- `onKernelRegister(): Promise<this>` — Phase `onRegister` : valide la config (défauts + override `module-frontend`) via `defineFrontendConfig`, puis la ré-assigne à `this.options` AVANT l'instanciation du `@services` (`FrontendService` lit …
- `onKernelBoot(): Promise<this>` — Phase `onBoot` : enregistre le producteur admin (`/nodefony/frontend/api/*`) auprès du broker, AVANT que framework ne monte le data plane à `onReady`.
- `onKernelReady(): Promise<this>`

#### `FrontendError`

```ts
class FrontendError extends Error
```

Erreur de base pour

- `readonly code: string`
- `readonly context?: Record<string, unknown>`
- `constructor(message: string, code: string, context?: Record<string, unknown>)`

#### `FrontendNoEntriesError`

```ts
class FrontendNoEntriesError extends FrontendError
```

Aucune entrée front trouvée alors qu'on tente de démarrer le dev server.

- `constructor()`

#### `FrontendPresetUnknownError`

```ts
class FrontendPresetUnknownError extends FrontendError
```

Preset inconnu — module a déclaré `type: "foo"` non enregistré.

- `constructor(type: string)`

#### `FrontendService`

```ts
class FrontendService extends Service implements IFrontendService
```

Service injectable du module `@nodefony/frontend`.

- `module: Module`
- `constructor(module: Module)`
- `assetUrl(p: string): string` — Résout l'URL publique d'un asset.
- `init(): Promise<this>`
- `registerEntry(consumerModule: Module, declaration: IFrontendModuleDeclaration): IResolvedFrontendEntry` — Enregistre une déclaration frontend d'un module consommateur.
- `listEntries(): ReadonlyArray<IResolvedFrontendEntry>` — Entrées front résolues (snapshot lecture).
- `status(): IViteSupervisorStatus` — État de l'instance Vite primaire (`default`), pour compat.
- `statusAll(): ReadonlyArray<{ family: string; status: IViteSupervisorStatus; }>` — État de **chaque** instance Vite, étiqueté par famille d'isolation (`default`, `angular`, …).
- `startDev(): Promise<void>` — Démarre une instance Vite **par famille d'isolation** (multi-supervisor).
- `stopDev(): Promise<void>` — Stoppe proprement le superviseur.
- `build(opts?: { force?: boolean; }): Promise<IFrontendBuildResult>` — Build production — `vite.build()` **par entry** (chaque bundle a son propre `root`/`outDir`/`base`/`manifest` : multi-module + isolation Angular).
- `renderDocument(entryName: string, nonce?: string): string` — Document HTML complet pour une entrée — lit l'`index.html` du module (le dev y met meta/polices/scripts externes) + injecte les tags Nodefony.
- `renderTags(entryName: string, nonce?: string): string` — Helper template — retourne les balises `<script>` à injecter dans une page.

#### `FrontendSupervisorStartError`

```ts
class FrontendSupervisorStartError extends FrontendError
```

Echec de démarrage de Vite (spawn raté, port occupé, config invalide).

- `constructor(reason: string, cause?: unknown)`

#### `TemplateHelper`

```ts
class TemplateHelper
```

Génère les balises HTML à injecter dans la page rendue côté serveur pour brancher le frontend Vite.

- `constructor(supervisor: IViteSupervisor | null, mode: "development" | "production", entries?: ReadonlyArray<IResolvedFrontendEntry>, assetBaseUrl?: string)`
- `devTarget(): string` — Origine LOCALE du serveur Vite — la cible du proxy inverse que Nodefony monte sur `/_vite/<famille>/` (#528).
- `renderTags(entryName: string, nonce?: string): string` — Tags à injecter dans `<head>` (ou avant `</body>`) pour une entrée donnée.
- `renderDocument(entryName: string, nonce?: string): string` — Document HTML complet pour une entrée : lit l'`index.html` du module (le dev y met SES meta/polices/scripts externes), retire le `<script type=module>` de l'entrée source (Vite-native, non résolvable …

#### `ViteBuilder`

```ts
class ViteBuilder implements IFrontBuilder
```

Construit la config Vite finale à partir des entrées résolues et des presets.

- `constructor()`
- `listPresets(): ReadonlyArray<IFrontPreset>` — Liste tous les presets enregistrés.
- `getPreset(type: IFrontPreset["type"]): IFrontPreset` — Récupère un preset par type.
- `registerPreset(preset: IFrontPreset): void` — Enregistre / remplace un preset.
- `buildViteConfig(entries: ReadonlyArray<IResolvedFrontendEntry>, mode: "development" | "production", assetBaseUrl?: string): Promise<Record<string, unknown>>` — Construit la config Vite (objet brut) pour une liste d'entrées résolues.

#### `ViteConfigGenerator`

```ts
class ViteConfigGenerator
```

- `toMjs(entries: ReadonlyArray<IResolvedFrontendEntry>, mode: "development" | "production", opts?: ViteConfigGeneratorOptions): string` — Construit le content `.mjs` à écrire à côté de `index.html` du module.

#### `ViteProcessSupervisor`

```ts
class ViteProcessSupervisor implements IViteSupervisor
```

Superviseur Vite résilient — branche POC `poc/frontend-child`.

- `constructor(opts: ViteSupervisorOptions)`
- `start(entries: ReadonlyArray<IResolvedFrontendEntry>, _viteConfigUnused: Record<string, unknown>): Promise<void>`
- `stop(): Promise<void>`
- `status(): IViteSupervisorStatus`

#### `default`

```ts
class Frontend extends Module<IFrontendConfig>
```

- `constructor(kernel: Kernel)`
- `configSchema(): unknown` — JSON Schema de la config frontend → data plane admin (config riche Studio).
- `onKernelRegister(): Promise<this>` — Phase `onRegister` : valide la config (défauts + override `module-frontend`) via `defineFrontendConfig`, puis la ré-assigne à `this.options` AVANT l'instanciation du `@services` (`FrontendService` lit …
- `onKernelBoot(): Promise<this>` — Phase `onBoot` : enregistre le producteur admin (`/nodefony/frontend/api/*`) auprès du broker, AVANT que framework ne monte le data plane à `onReady`.
- `onKernelReady(): Promise<this>`

### Fonctions (4)

#### `buildFrontendStatus`

```ts
function buildFrontendStatus(service: FrontendService): IFrontendStatusView
```

Construit le snapshot frontend (état Vite) — lecture pure, jamais throw.

#### `createFrontendAdminApi`

```ts
function createFrontendAdminApi(service: FrontendService): IAdminApi
```

Construit le producteur `IAdminApi` du frontend (namespace `"frontend"`).

#### `defineFrontendConfig`

```ts
function defineFrontendConfig(config?: IFrontendConfigInput): IFrontendConfig
```

Builder type-safe de la configuration de `@nodefony/frontend`.

#### `frontendConfigJsonSchema`

```ts
function frontendConfigJsonSchema(): unknown
```

JSON Schema introspectable de la config frontend — destiné au panneau de config Studio (`/nodefony/config`).

### Constantes (6)

#### `angularPreset`

```ts
const angularPreset: IFrontPreset
```

Preset Angular (17+ standalone) + Vite via `@analogjs/vite-plugin-angular`.

#### `frontendConfigSchema`

```ts
const frontendConfigSchema: z.ZodObject<{ devHost: z.ZodDefault<z.ZodString>; devPort: z.ZodDefault<z.ZodNumber>; autoStartInDevelopment: z.ZodDefault<z.ZodBoolean>; defaultOutDir: z.ZodDefault<z.ZodString>; defaultRoot: z.ZodDefault<z.ZodString>; assetBaseUrl: z.ZodDefault<z.ZodString>; startupTimeoutMs: z.ZodDefault<z.ZodNumber>; pipeViteLogs: z.ZodDefault<z.ZodBoolean>; viteEnv: z.ZodDefault<z. …
```

#### `react19Preset`

```ts
const react19Preset: IFrontPreset
```

Preset React 19 + Vite.

#### `svelte5Preset`

```ts
const svelte5Preset: IFrontPreset
```

Preset Svelte 5 + Vite.

#### `vanillaPreset`

```ts
const vanillaPreset: IFrontPreset
```

Preset vanilla — TS/JS sans framework.

#### `vue3Preset`

```ts
const vue3Preset: IFrontPreset
```

Preset Vue 3 + Vite.

### Interfaces (9)

#### `IFrontBuilder`

```ts
interface IFrontBuilder
```

Builder responsable de construire la config Vite finale à partir des déclarations modules + des presets.

- `listPresets(): ReadonlyArray<IFrontPreset>` — Liste tous les presets enregistrés.
- `getPreset(type: IFrontPreset["type"]): IFrontPreset` — Récupère un preset par type.
- `registerPreset(preset: IFrontPreset): void` — Enregistre / remplace un preset.
- `buildViteConfig(entries: ReadonlyArray<IResolvedFrontendEntry>, mode: "development" | "production"): Promise<Record<string, unknown>>` — Construit la config Vite (objet brut) pour une liste d'entrées résolues.

#### `IFrontPreset`

```ts
interface IFrontPreset
```

- `readonly type: FrontPresetType` — Identifiant unique du preset (ex: "react19").
- `readonly extensions: ReadonlyArray<string>` — Extensions sources reconnues (".tsx", ".vue", ".svelte"…).
- `readonly optimizeDepsInclude: ReadonlyArray<string>` — Dépendances à pré-scanner via `optimizeDeps.include`.
- `buildPlugins(): Promise<unknown[]>` — Construit la liste des plugins Vite à injecter.

#### `IFrontendModuleDeclaration`

```ts
interface IFrontendModuleDeclaration
```

Déclaration frontend portée par un module consommateur dans son `config.ts` :

- `readonly type: IFrontPreset["type"]` — Type de preset (résolu vers un IFrontPreset).
- `readonly entry: string` — Entrée source relative à la racine du module (ex: "./frontend/src/main.tsx").
- `readonly outDir?: string` — Dossier de sortie de la prod build (relatif au module, défaut "./public/dist").
- `readonly root?: string` — Racine front (contient index.html), défaut "./frontend".
- `readonly name?: string` — Nom logique de l'entrée multi-bundle (défaut = nom du module).
- `readonly publicPath?: string` — Préfixe public sous lequel les assets buildés sont servis en prod (par le serveur statique `Statics` de

#### `IFrontendService`

```ts
interface IFrontendService
```

API publique du `FrontendService` injectable.

- `listEntries(): ReadonlyArray<IResolvedFrontendEntry>` — Entrées front résolues (snapshot lecture).
- `status(): IViteSupervisorStatus` — État de l'instance Vite primaire (`default`), pour compat.
- `statusAll(): ReadonlyArray<{ family: string; status: IViteSupervisorStatus; }>` — État de **chaque** instance Vite, étiqueté par famille d'isolation (`default`, `angular`, …).
- `startDev(): Promise<void>` — Lance le dev server (idempotent — premier appel boot).
- `stopDev(): Promise<void>` — Stoppe proprement le superviseur.
- `build(opts?: { force?: boolean; }): Promise<IFrontendBuildResult>` — Build production — `vite.build()` par entry (manifest.json par bundle).
- `renderTags(entryName: string, nonce?: string): string` — Helper template — retourne les balises `<script>` à injecter dans une page.
- `renderDocument(entryName: string, nonce?: string): string` — Document HTML complet : `index.html` du module + tags injectés.
- `assetUrl(p: string): string` — Résout l'URL publique d'un asset : préfixe `p` par `assetBaseUrl` (CDN) si configuré, sinon chemin relatif inchangé.

#### `IFrontendStatusView`

```ts
interface IFrontendStatusView
```

Snapshot frontend servi par l'endpoint `vite`.

- `available: boolean` — Au moins une instance Vite `ready` (HMR actif).
- `vite?: string` — Version de Vite (le builder), si résolue.
- `primary: IViteInstanceView` — Instance principale (famille `default` ou la première).
- `bundles: IViteInstanceView[]` — Toutes les instances (multi-bundle).

#### `IResolvedFrontendEntry`

```ts
interface IResolvedFrontendEntry
```

Description résolue d'une entrée front, prête à être passée au superviseur Vite.

- `readonly moduleName: string`
- `readonly entryName: string`
- `readonly type: IFrontPreset["type"]`
- `readonly root: string`
- `readonly entryFile: string`
- `readonly outDir: string`
- `readonly publicPath: string` — Préfixe public normalisé (leading + trailing `/`, ex `/_assets/studio/`) — `base` Vite en prod + mount prefix du serveur statique.

#### `IViteInstanceView`

```ts
interface IViteInstanceView
```

Vue SÛRE d'une instance Vite — sans chemins FS absolus (anti info-leak).

- `family: string` — Famille d'isolation (`default`, `angular`, …).
- `state: string` — État du superviseur (`ready` = HMR actif).
- `host: string` — Hôte d'ÉCOUTE du serveur Vite (dev).
- `origin: string | null` — Origine PUBLIQUE effective (celle que le navigateur utilise) — `null` si non démarré.
- `port: number | null` — Port RÉEL résolu (Vite incrémente si occupé) — `null` si non démarré.
- `pid: number | null` — PID du process enfant Vite — `null` hors dev.
- `https: boolean` — Vite servi en HTTPS (suit la config du serveur).
- `restartCount: number` — Redémarrages du superviseur depuis le boot.
- `healthFailures: number` — Échecs de health-check du superviseur.
- `entries: { entryName: string; type: string; version?: string; }[]` — Entrées servies — nom logique + type + version du framework UI.

#### `IViteSupervisor`

```ts
interface IViteSupervisor
```

Contrat du superviseur Vite — implémenté différemment selon la branche POC : - `poc/frontend-child` : ViteProcessSupervisor (child_process.spawn) - `poc/frontend-single` : ViteInProcSupervisor (vite.createServer() in-proc)

- `start(entries: ReadonlyArray<IResolvedFrontendEntry>, viteConfig: Record<string, unknown>): Promise<void>`
- `stop(): Promise<void>`
- `status(): IViteSupervisorStatus`

#### `IViteSupervisorStatus`

```ts
interface IViteSupervisorStatus
```

Snapshot lisible du superviseur, lu par TemplateHelper pour injecter les bons scripts (URL `host:port` Vite côté navigateur).

- `readonly state: ViteSupervisorState`
- `readonly host: string`
- `readonly port: number | null`
- `readonly origin: string | null` — Origine LOCALE du dev server (`http://127.0.0.1:<port réel>`) : la cible du proxy inverse de Nodefony.
- `readonly base?: string` — Chemin de base Vite de cette instance (`/_vite/<famille>/`, `/` en tête et en fin).
- `readonly pid: number | null`
- `readonly lastError: string | null`
- `readonly entries: ReadonlyArray<IResolvedFrontendEntry>`
- `readonly https: boolean` — Vite sert-il en HTTPS ?
- `readonly restartCount: number` — Nombre de redémarrages auto effectués depuis le premier `start()`.
- `readonly healthFailures: number` — Nombre d'échecs consécutifs du health check (reset à chaque succès).
- `readonly portRetries: number` — Nombre de REPLIS de port effectués au dernier démarrage — `0` quand Vite a pris le port demandé du premier coup.

### Types (4)

#### `FrontPresetType`

```ts
type FrontPresetType = "react19" | "vue3" | "angular" | "svelte5" | "vanilla"
```

Preset descriptor — applique une stack frontend (React, Vue, Angular, Svelte, vanilla).

#### `IFrontendConfig`

```ts
type IFrontendConfig = z.infer<typeof frontendConfigSchema>
```

Type de sortie (config normalisée + défauts appliqués).

#### `IFrontendConfigInput`

```ts
type IFrontendConfigInput = z.input<typeof frontendConfigSchema>
```

Entrée du builder (champs avec défaut optionnels).

#### `ViteSupervisorState`

```ts
type ViteSupervisorState = "idle" | "starting" | "ready" | "compiling" | "restarting" | "crashed" | "stopping" | "stopped" | "errored"
```

État courant du superviseur Vite — exposé pour observabilité (Vision, CLI).

---

[← Toutes les références d'API](../)