Référence d'API — @nodefony/frontend

stable

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#

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#

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#

class FrontendNoEntriesError extends FrontendError

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

• constructor()

FrontendPresetUnknownError#

class FrontendPresetUnknownError extends FrontendError

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

• constructor(type: string)

FrontendService#

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#

class FrontendSupervisorStartError extends FrontendError

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

• constructor(reason: string, cause?: unknown)

TemplateHelper#

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#

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#

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#

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#

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#

function buildFrontendStatus(service: FrontendService): IFrontendStatusView

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

createFrontendAdminApi#

function createFrontendAdminApi(service: FrontendService): IAdminApi

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

defineFrontendConfig#

function defineFrontendConfig(config?: IFrontendConfigInput): IFrontendConfig

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

frontendConfigJsonSchema#

function frontendConfigJsonSchema(): unknown

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

Constantes (6)#

angularPreset#

const angularPreset: IFrontPreset

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

frontendConfigSchema#

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#

const react19Preset: IFrontPreset

Preset React 19 + Vite.

svelte5Preset#

const svelte5Preset: IFrontPreset

Preset Svelte 5 + Vite.

vanillaPreset#

const vanillaPreset: IFrontPreset

Preset vanilla — TS/JS sans framework.

vue3Preset#

const vue3Preset: IFrontPreset

Preset Vue 3 + Vite.

Interfaces (9)#

IFrontBuilder#

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#

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#

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#

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#

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#

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#

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#

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#

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#

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

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

IFrontendConfig#

type IFrontendConfig = z.infer<typeof frontendConfigSchema>

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

IFrontendConfigInput#

type IFrontendConfigInput = z.input<typeof frontendConfigSchema>

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

ViteSupervisorState#

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