odoro 1.0.9 → 2.1.0

package/dist/index.d.ts

@@ -1,110 +1,305 @@
+import { Plugin, BuildResult } from 'esbuild';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
 /**
- * Configuration du moteur Odoro.
+ * Engine plugins.
+ *
+ * ## Why such a small surface
+ *
+ * A plugin system is a compatibility promise: everything it exposes will have
+ * to be honoured. This one exposes only what a project really needs —
+ * transform code, transform the document, add a route to the server — and
+ * leaves an escape hatch towards the bundler for the rest.
  *
- * Le fichier `odoro.config.ts` est compile a la volee puis importe : il peut
- * donc etre ecrit en TypeScript et utiliser toute la puissance du langage,
- * sans etape de build prealable.
+ * Three hooks can be replaced; thirty get dragged along.
  *
  * @module
  */
-/** Reglages du serveur de developpement. */
+
+/** What a plugin knows about the transformation under way. */
+interface TransformContext {
+    /** Absolute path of the transformed file. */
+    readonly id: string;
+    /** True during development, false in a production build. */
+    readonly dev: boolean;
+    /** True during a server render (prerendering). */
+    readonly ssr: boolean;
+}
+/** What a plugin knows about the document it transforms. */
+interface HtmlContext {
+    /** True during development. */
+    readonly dev: boolean;
+    /** Route being rendered, during a prerender; `/` otherwise. */
+    readonly route: string;
+}
+/** A request middleware, added to the development server. */
+type Middleware = (request: IncomingMessage, response: ServerResponse, next: () => void) => void | Promise<void>;
+/** What a plugin receives to hook into the server. */
+interface ServerContext {
+    /** Adds a middleware, called before the engine handles the request. */
+    use(middleware: Middleware): void;
+}
+/**
+ * A plugin.
+ *
+ * @example
+ * import { defineConfig, type OdoroPlugin } from 'odoro'
+ *
+ * const stamped: OdoroPlugin = {
+ *   name: 'stamped',
+ *   transformIndexHtml: (html) =>
+ *     html.replace('</head>', `<meta name="build" content="${Date.now()}"></head>`),
+ * }
+ *
+ * export default defineConfig({ plugins: [stamped] })
+ */
+interface OdoroPlugin {
+    /** Plugin name, shown in error messages. */
+    readonly name: string;
+    /**
+     * Transforms the code of a source file before it is compiled.
+     *
+     * Returning `null` or `undefined` leaves the file untouched — that is what to
+     * do for everything the plugin is not concerned with, and it is cheaper than
+     * returning the unchanged code.
+     */
+    transform?(code: string, context: TransformContext): string | null | undefined | Promise<string | null | undefined>;
+    /** Transforms the HTML document before it is served or written. */
+    transformIndexHtml?(html: string, context: HtmlContext): string | Promise<string>;
+    /** Hooks middlewares into the development server. */
+    configureServer?(context: ServerContext): void | Promise<void>;
+    /**
+     * Bundler plugins, for what the hooks above do not cover.
+     *
+     * This is the escape hatch: it grants access to full resolution and loading,
+     * at the price of coupling to the bundler.
+     */
+    readonly esbuild?: readonly Plugin[];
+}
+
+/**
+ * Configuration of the Odoro engine.
+ *
+ * The `odoro.config.ts` file is compiled on the fly then imported: it can
+ * therefore be written in TypeScript and use the full power of the language,
+ * with no prior build step.
+ *
+ * @module
+ */
+
+/** Certificate of an HTTPS development server. */
+interface HttpsConfig {
+    /** Path to the certificate, relative to the project root. */
+    cert: string;
+    /** Path to the private key, relative to the project root. */
+    key: string;
+}
+/** Development server settings. */
 interface ServerConfig {
-    /** Port d'ecoute. @defaultValue 5180 */
+    /** Port to listen on. @defaultValue 5180 */
     port?: number;
-    /** Interface d'ecoute. @defaultValue 'localhost' */
+    /** Interface to listen on. @defaultValue 'localhost' */
     host?: string;
     /**
-     * Redirections de requetes, du prefixe de chemin vers l'origine cible.
+     * Request forwarding, from path prefix to target origin.
      *
      * @example
      * { '/api': 'http://localhost:3001' }
      */
     proxy?: Record<string, string>;
+    /**
+     * Serves over HTTPS, with the given certificate.
+     *
+     * Required as soon as an interface demands a secure origin: camera,
+     * microphone, clipboard, service worker.
+     */
+    https?: HttpsConfig;
+    /**
+     * Fails if the requested port is taken, instead of sliding to the next one.
+     *
+     * @defaultValue false
+     */
+    strictPort?: boolean;
+    /** Opens the browser on startup. @defaultValue false */
+    open?: boolean;
+}
+/** Prerendering settings. */
+interface PrerenderConfig {
+    /**
+     * The routes rendered at build time.
+     *
+     * When empty, the ones the server entry exports under the name `routes` are
+     * taken.
+     */
+    routes?: readonly string[];
+    /**
+     * Server entry, relative to the root.
+     *
+     * @defaultValue 'src/entry-server.tsx'
+     */
+    entry?: string;
 }
-/** Reglages de la compilation de production. */
+/** Production build settings. */
 interface BuildConfig {
-    /** Dossier de sortie, relatif a la racine. @defaultValue 'dist' */
+    /** Output directory, relative to the root. @defaultValue 'dist' */
     outDir?: string;
-    /** Minifie le code produit. @defaultValue true */
+    /** Minifies the produced code. @defaultValue true */
     minify?: boolean;
-    /** Emet des cartes de source. @defaultValue true */
+    /** Emits source maps. @defaultValue true */
     sourcemap?: boolean;
-    /** Cible de compilation. @defaultValue 'es2022' */
+    /** Build target. @defaultValue 'es2022' */
     target?: string;
     /**
-     * Retire de la feuille de style les classes utilitaires que rien n'emploie.
+     * Removes from the stylesheet the utility classes nothing uses.
      *
-     * La bibliotheque livre une feuille pre-generee qui les contient toutes ;
-     * une application donnee en emploie une fraction. L'elagage lit le code
-     * **produit** — donc les composants de bibliotheque autant que la source de
-     * l'application — et ne garde que ce qui est atteignable.
+     * The library ships a pre-generated stylesheet holding them all; a given
+     * application uses a fraction of it. Pruning reads the **produced** code —
+     * so the library components as much as the application source — and keeps
+     * only what is reachable.
      *
-     * Une classe assemblee a l'execution (`o-text-${couleur}`) n'existe nulle
-     * part sous sa forme finale et disparaitra : la declarer dans
-     * `safelist` est le seul moyen de la garder.
+     * A class assembled at runtime (`o-text-${color}`) exists nowhere in its
+     * final form and will disappear: declaring it in `safelist` is the only way
+     * to keep it.
      *
      * @defaultValue true
      */
-    elaguer?: boolean;
+    prune?: boolean;
     /**
-     * Les classes gardees quoi qu'il arrive, malgre l'elagage.
+     * The classes kept no matter what, despite pruning.
      *
-     * Une chaine garde une classe ; une expression reguliere garde toutes celles
-     * qu'elle reconnait.
+     * A string keeps one class; a regular expression keeps every class it
+     * matches.
      *
      * @example
      * { safelist: [/^o-text-/, 'o-animate-spin'] }
      */
     safelist?: readonly (string | RegExp)[];
+    /**
+     * Writes `manifest.json` next to the produced files.
+     *
+     * It gives, for each entry, the hashed file, its stylesheets and its chunks.
+     * That is what a server reads to place the tags itself, when the project
+     * document does not carry them.
+     *
+     * @defaultValue true
+     */
+    manifest?: boolean;
+    /**
+     * Declares the shared chunks as `modulepreload` in the document.
+     *
+     * Without it, the browser only discovers a chunk after reading the module
+     * that imports it: as many round trips as there are levels of depth, on the
+     * critical path.
+     *
+     * @defaultValue true
+     */
+    preload?: boolean;
+    /**
+     * Renders the routes to HTML at build time.
+     *
+     * `true` takes the defaults; an array gives the routes; the object form
+     * allows naming another entry point.
+     *
+     * @defaultValue false
+     *
+     * @example
+     * { prerender: ['/', '/about'] }
+     */
+    prerender?: boolean | readonly string[] | PrerenderConfig;
 }
-/** Configuration d'un projet Odoro. */
+/** Configuration of an Odoro project. */
 interface OdoroConfig {
-    /** Racine du projet. @defaultValue le dossier courant */
+    /** Project root. @defaultValue the current directory */
     root?: string;
-    /** Prefixe des URL publiques. @defaultValue '/' */
+    /** Prefix of public URLs. @defaultValue '/' */
     base?: string;
-    /** Dossier des fichiers copies tels quels. @defaultValue 'public' */
+    /** Directory of files copied as is. @defaultValue 'public' */
     publicDir?: string;
-    /** Reglages du serveur de developpement. */
+    /** Development server settings. */
     server?: ServerConfig;
-    /** Reglages de la compilation de production. */
+    /** Production build settings. */
     build?: BuildConfig;
     /**
-     * Alias de chemins d'import, du prefixe vers un chemin relatif a la racine.
+     * Import path aliases, from prefix to a path relative to the root.
      *
      * @example
      * { '@': 'src' }
      */
     alias?: Record<string, string>;
-    /** Remplacements textuels appliques a la compilation. */
+    /** Textual replacements applied at build time. */
     define?: Record<string, string>;
     /**
-     * Prefixe des variables d'environnement exposees au client via
+     * Prefix of the environment variables exposed to the client through
      * `import.meta.env`.
      *
      * @defaultValue 'ODORO_'
      */
     envPrefix?: string;
+    /**
+     * Directory where the `.env` files are looked up.
+     *
+     * @defaultValue the project root
+     */
+    envDir?: string;
+    /**
+     * Build mode: it chooses the `.env` files read and feeds
+     * `import.meta.env.MODE`.
+     *
+     * @defaultValue 'development' for `dev`, 'production' for `build`
+     */
+    mode?: string;
+    /** Plugins applied to the build and to the server. */
+    plugins?: readonly OdoroPlugin[];
+}
+/** Prerendering, once resolved. */
+interface ResolvedPrerender {
+    /** Routes to render; when empty, those of the server entry. */
+    readonly routes: readonly string[];
+    /** Absolute path of the server entry. */
+    readonly entry: string;
 }
-/** Configuration une fois les valeurs par defaut appliquees. */
+/** Production build, once resolved. */
+interface ResolvedBuild {
+    readonly outDir: string;
+    readonly minify: boolean;
+    readonly sourcemap: boolean;
+    readonly target: string;
+    readonly prune: boolean;
+    readonly safelist: readonly (string | RegExp)[];
+    readonly manifest: boolean;
+    readonly preload: boolean;
+    /** `undefined` when prerendering is not requested. */
+    readonly prerender: ResolvedPrerender | undefined;
+}
+/** Configuration once the default values are applied. */
 interface ResolvedConfig {
     readonly root: string;
     readonly base: string;
     readonly publicDir: string;
     readonly outDir: string;
-    readonly server: Required<Omit<ServerConfig, 'proxy'>> & {
+    readonly server: Required<Omit<ServerConfig, 'proxy' | 'https'>> & {
         proxy: Record<string, string>;
+        https: HttpsConfig | undefined;
     };
-    readonly build: Required<BuildConfig>;
+    readonly build: ResolvedBuild;
     readonly alias: Record<string, string>;
     readonly define: Record<string, string>;
     readonly envPrefix: string;
-    /** Chemin du fichier de configuration effectivement charge, s'il existe. */
+    readonly envDir: string;
+    /** Mode retained. */
+    readonly mode: string;
+    /** Every variable read, prefixed or not. Never leaves the machine. */
+    readonly env: Readonly<Record<string, string>>;
+    /** What the client code reads in `import.meta.env`. */
+    readonly envClient: Readonly<Record<string, string | boolean>>;
+    /** Plugins declared by the project. */
+    readonly plugins: readonly OdoroPlugin[];
+    /** Path of the configuration file actually loaded, if there is one. */
     readonly configFile: string | undefined;
 }
 /**
- * Identite sur la configuration, presente uniquement pour le typage et
- * l'autocompletion dans `odoro.config.ts`.
+ * Identity on the configuration, present only for typing and completion in
+ * `odoro.config.ts`.
  *
  * @example
  * import { defineConfig } from 'odoro'
@@ -115,38 +310,290 @@ interface ResolvedConfig {
  */
 declare function defineConfig(config: OdoroConfig): OdoroConfig;
 /**
- * Charge la configuration d'un projet et applique les valeurs par defaut.
+ * Loads the configuration of a project and applies the default values.
  *
- * @param root Racine du projet.
- * @param overrides Reglages issus de la ligne de commande, prioritaires.
+ * @param root Project root.
+ * @param overrides Settings coming from the command line, which take priority.
+ * @param defaultMode Mode retained when neither the command line nor the
+ *   configuration file names one.
  *
  * @example
  * const config = await loadConfig(process.cwd(), { server: { port: 4000 } })
  */
-declare function loadConfig(root: string, overrides?: OdoroConfig): Promise<ResolvedConfig>;
+declare function loadConfig(root: string, overrides?: OdoroConfig, defaultMode?: string): Promise<ResolvedConfig>;
 
+/** What loading produced. */
+interface LoadedEnv {
+    /** Every value read, prefixed or not. */
+    readonly all: Record<string, string>;
+    /** The only values exposed to the client, the prefixed ones. */
+    readonly client: Record<string, string>;
+    /** The files actually read, in order. */
+    readonly files: readonly string[];
+}
 /**
- * Serveur de developpement.
+ * Loads the environment files of a project.
+ *
+ * ## What wins, and why
+ *
+ * A variable already present in the process environment is **never** overwritten
+ * by a file. That is the only rule that makes a deployment predictable: a `.env`
+ * versioned by mistake must not take precedence over the value the host
+ * injects.
  *
- * Aucune compilation prealable : le navigateur demande les modules un a un,
- * en modules natifs, et chacun est compile a la demande puis mis en cache.
- * Le temps de demarrage ne depend donc pas de la taille du projet, seulement
- * de la profondeur du premier ecran.
+ * ## What goes to the browser
+ *
+ * The prefix alone. A variable without the prefix stays readable by the command
+ * — a database token, a server API key — and does not leave the machine:
+ * everything that enters `import.meta.env` ends up in clear text in the
+ * published bundle, and nothing catches it afterwards.
+ *
+ * @param directory Directory where the files are looked up.
+ * @param mode Build mode (`development`, `production`, or your own).
+ * @param prefix Prefix of the variables exposed to the client.
+ *
+ * @example
+ * const env = await loadEnv('/project', 'production', 'ODORO_')
+ * env.client // { ODORO_API: 'https://api.odoro.dev' }
+ */
+declare function loadEnv(directory: string, mode: string, prefix: string): Promise<LoadedEnv>;
+/**
+ * Assembles the values the client code reads in `import.meta.env`.
+ *
+ * @example
+ * clientEnv({ ODORO_API: 'x' }, 'production', '/')
+ * // { MODE: 'production', DEV: false, PROD: true, BASE_URL: '/', ODORO_API: 'x' }
+ */
+declare function clientEnv(variables: Readonly<Record<string, string>>, mode: string, base: string): Record<string, string | boolean>;
+
+/** What the transformation produced. */
+interface Resolution {
+    /** Transformed code. */
+    readonly code: string;
+    /** Files reached, as absolute paths. */
+    readonly files: readonly string[];
+}
+/** Tells whether some code uses import by pattern. */
+declare function hasGlob(code: string): boolean;
+/**
+ * Replaces the calls to `import.meta.glob` by tables of static imports.
+ *
+ * @param code Source of the module.
+ * @param file Absolute path of the module.
+ * @param projectRoot Project root, for patterns starting with `/`.
+ * @returns The transformed code, or `undefined` if nothing changed.
+ *
+ * @example
+ * transformGlob("const p = import.meta.glob('./pages/*.tsx')", file, root)
+ * // const p = {"./pages/index.tsx": () => import("./pages/index.tsx")}
+ */
+declare function transformGlob(code: string, file: string, projectRoot: string): Resolution | undefined;
+
+/**
+ * The build manifest, and the preloading it enables.
+ *
+ * ## Two needs, a single reading
+ *
+ * The bundler report knows everything: which file comes from which source,
+ * which stylesheet goes with which script, which chunk is shared by which
+ * modules. It is written in a format of its own, and it disappears at the end
+ * of the build.
+ *
+ * Two things depend on it. A server that places the tags itself — because the
+ * document is rendered elsewhere, by a template engine or by the back end —
+ * needs to know what to point at; that is `manifest.json`. And the browser
+ * gains from knowing the chunks **before** having read the module that imports
+ * them; that is preloading.
  *
  * @module
  */
 
-/** Serveur de developpement en cours d'execution. */
+/** What the manifest says about a produced file. */
+interface ManifestEntry {
+    /** Path of the produced file, relative to the output directory. */
+    readonly file: string;
+    /** Source it comes from, relative to the root. Absent for a chunk. */
+    readonly src?: string;
+    /** True when it is an entry of the document. */
+    readonly isEntry?: boolean;
+    /** Stylesheets to place alongside it. */
+    readonly css?: readonly string[];
+    /** Chunks it imports statically, by their key in the manifest. */
+    readonly imports?: readonly string[];
+    /** Chunks it imports on demand. */
+    readonly dynamicImports?: readonly string[];
+}
+/** The whole manifest. */
+type Manifest = Readonly<Record<string, ManifestEntry>>;
+/** What is needed to read the report. */
+interface Context {
+    /** Project root — the paths of the report are relative to it. */
+    readonly root: string;
+    /** Directory where the produced files are written. */
+    readonly assetsDir: string;
+    /**
+     * The entries of the document, as absolute paths.
+     *
+     * ## Why they have to be given
+     *
+     * The report assigns an `entryPoint` to every module that **opens a chunk** —
+     * so to every module imported on demand, which splitting isolates by
+     * construction. Taking those for document entries would make a server place
+     * one `<script>` tag per lazy page: everything would be loaded up front, and
+     * splitting would have served no purpose.
+     *
+     * Only the document knows which ones are its own.
+     */
+    readonly entries?: readonly string[];
+}
+/**
+ * Builds the manifest from the build report.
+ *
+ * The keys are the **sources** for the entries — that is the name a server
+ * looks them up under, `src/main.tsx` and not `main-A1B2.js`, which it cannot
+ * guess — and the produced file for the chunks, which have no single source.
+ *
+ * @example
+ * const manifest = buildManifest(result, { root, assetsDir })
+ * manifest['src/main.tsx'].file // 'main-A1B2.js'
+ */
+declare function buildManifest(result: BuildResult<{
+    metafile: true;
+}>, context: Context): Manifest;
+/**
+ * The chunks to preload for a given entry.
+ *
+ * ## Why the transitive ones count
+ *
+ * The browser discovers a chunk by reading the module that imports it. A chunk
+ * imported by a chunk therefore only appears on the third round trip — one per
+ * level of depth, each on the critical path, and splitting multiplies them by
+ * construction.
+ *
+ * Declaring them all up front puts them in flight at the same time.
+ *
+ * ## What is not in there
+ *
+ * The imports on demand. Those are the ones deliberately deferred — a page the
+ * visitor may never open. Preloading them would cancel the splitting while
+ * keeping its cost.
+ *
+ * @param entry The produced file for the entry, as the report names it.
+ * @returns The files to preload, relative to the produced files directory.
+ */
+declare function chunksFor(result: BuildResult<{
+    metafile: true;
+}>, entry: string, context: Context): string[];
+
+/**
+ * Suffixed imports, on the build side: `?worker`, `?raw`, `?url`.
+ *
+ * @module
+ */
+
+/** What changes between the client build and the prerender. */
+interface AssetOptions {
+    /**
+     * Receives the paths of the files written **outside** the main build — those
+     * of the workers. Without it, they would appear in no summary: the report of
+     * the main build does not know them, and a hundred-kilobyte bundle would land
+     * in the output directory without anything announcing it.
+     */
+    readonly outputs: Set<string>;
+    /**
+     * True during the prerender.
+     *
+     * It builds nothing new: everything has already been produced for the client,
+     * and doing it again would drop a second copy of each asset, under another
+     * hash.
+     */
+    readonly ssr?: boolean;
+    /**
+     * The public addresses already assigned, from the source file to its URL.
+     *
+     * ## Why they must be the same
+     *
+     * An image written in the prerendered HTML and the same image loaded by the
+     * script must point to the same place. Letting the prerender recompute the
+     * address would produce two hashes for a single file: one exists, the other
+     * does not, and the prerendered page would show a broken image until
+     * hydration replaced it — that is, precisely in front of the people the
+     * prerender is for.
+     */
+    readonly urls?: ReadonlyMap<string, string>;
+}
+
+/**
+ * Prerendering: the routes become HTML at build time.
+ *
+ * ## Why this is the missing piece
+ *
+ * A single-page application ships an empty document and a script. A visitor
+ * does not see it — the script runs in a few dozen milliseconds — but a robot
+ * does: a search engine that does not run the script, a link preview that reads
+ * only the tags of the document, a screen reader that starts before hydration.
+ * For them, a marketing site published as a single page is a blank page.
+ *
+ * ## Why at build time, and not on demand
+ *
+ * Rendering on every request would require a Node process in production, hence
+ * a host that keeps one, hence monitoring, memory, a restart. Rendering at
+ * build time produces files: the site stays served by any static server, and
+ * prerendering costs nothing after the build.
+ *
+ * The price is that the routes must be known up front. That is the case of a
+ * marketing site, which is what this command serves.
+ *
+ * @module
+ */
+
+/** What a server entry may return. */
+type RouteRender = string | {
+    /** The HTML placed in the application container. */
+    html: string;
+    /** Tags added to `<head>` — title, description, preview. */
+    head?: string;
+};
+/** What the prerender produced. */
+interface PrerenderOutput {
+    /** The files written, relative to the output directory. */
+    readonly pages: readonly string[];
+}
+/**
+ * Renders the configured routes and writes one document per route.
+ *
+ * @param config Resolved configuration of the project.
+ * @param document The document already rewritten towards the hashed files.
+ * @param assets The addresses the client build assigned, so that the rendered
+ *   HTML points at the same files.
+ *
+ * @example
+ * await prerender(config, html)
+ */
+declare function prerender(config: ResolvedConfig, document: string, assets?: AssetOptions): Promise<PrerenderOutput>;
+
+/**
+ * Development server.
+ *
+ * No prior build: the browser asks for the modules one by one, as native
+ * modules, and each is compiled on demand then cached. The start time therefore
+ * does not depend on the size of the project, only on the depth of the first
+ * screen.
+ *
+ * @module
+ */
+
+/** Running development server. */
 interface DevServer {
-    /** Adresse a ouvrir dans un navigateur. */
+    /** Address to open in a browser. */
     readonly url: string;
-    /** Arrete le serveur et libere les ressources. */
+    /** Stops the server and releases the resources. */
     close(): Promise<void>;
 }
 /**
- * Demarre le serveur de developpement.
+ * Starts the development server.
  *
- * @param config Configuration resolue du projet.
+ * @param config Resolved configuration of the project.
  *
  * @example
  * const server = await startDevServer(await loadConfig(process.cwd()))
@@ -155,66 +602,73 @@ interface DevServer {
 declare function startDevServer(config: ResolvedConfig): Promise<DevServer>;
 
 /**
- * Compilation de production.
+ * Production build.
  *
- * Le document HTML est le point de depart : ses balises de script en modules
- * designent les entrees, et il est reecrit a la fin pour pointer vers les
- * fichiers empreintes.
+ * The HTML document is the starting point: its module script tags designate the
+ * entries, and it is rewritten at the end to point at the hashed files.
  *
  * @module
  */
 
-/** Un fichier produit par la compilation. */
+/** A file produced by the build. */
 interface BuiltFile {
-    /** Chemin relatif au dossier de sortie. */
+    /** Path relative to the output directory. */
     readonly path: string;
-    /** Taille en octets. */
+    /** Size in bytes. */
     readonly bytes: number;
+    /**
+     * Size once compressed, for text files.
+     *
+     * That is the one that counts: no server ships uncompressed JavaScript.
+     * Announcing the raw bytes makes every bundle look three times heavier than
+     * it arrives, and makes any trade-off on weight wrong.
+     */
+    readonly gzip?: number;
 }
-/** Resultat d'une compilation de production. */
+/** Result of a production build. */
 interface BuildOutput {
-    /** Dossier de sortie. */
+    /** Output directory. */
     readonly outDir: string;
-    /** Fichiers produits, du plus gros au plus petit. */
+    /** Files produced, from largest to smallest. */
     readonly files: readonly BuiltFile[];
-    /** Duree totale, en millisecondes. */
+    /** Total duration, in milliseconds. */
     readonly elapsed: number;
 }
 /**
- * Compile un projet pour la production.
+ * Builds a project for production.
  *
- * @param config Configuration resolue du projet.
+ * @param config Resolved configuration of the project.
  *
  * @example
  * const output = await buildProject(await loadConfig(process.cwd()))
  */
 declare function buildProject(config: ResolvedConfig): Promise<BuildOutput>;
-/** Affiche le recapitulatif d'une compilation. */
+/** Prints the summary of a build. */
 declare function reportBuild(output: BuildOutput, root: string): void;
 
 /**
- * Serveur de previsualisation du build de production.
+ * Preview server for the production build.
  *
- * Il ne compile rien : il sert le dossier de sortie tel quel, avec le meme
- * repli d'application monopage qu'un hebergeur statique. C'est le dernier
- * filet avant un deploiement.
+ * It builds nothing: it serves the output directory as it is, with the same
+ * single-page application fallback a static host uses. This is the last safety
+ * net before a deployment.
  *
  * @module
  */
 
-/** Serveur de previsualisation en cours d'execution. */
+/** Running preview server. */
 interface PreviewServer {
-    /** Adresse a ouvrir dans un navigateur. */
+    /** Address to open in a browser. */
     readonly url: string;
-    /** Arrete le serveur. */
+    /** Stops the server. */
     close(): Promise<void>;
 }
 /**
- * Demarre le serveur de previsualisation.
+ * Starts the preview server.
  *
- * @param config Configuration resolue du projet.
- * @param port Port d'ecoute. Par defaut, celui du serveur de developpement
- *   augmente de un, pour pouvoir faire tourner les deux.
+ * @param config Resolved configuration of the project.
+ * @param port Port to listen on. By default, the development server port plus
+ *   one, so that both can run.
  *
  * @example
  * const preview = await startPreviewServer(config)
@@ -222,158 +676,156 @@ interface PreviewServer {
 declare function startPreviewServer(config: ResolvedConfig, port?: number): Promise<PreviewServer>;
 
 /**
- * Graphe des modules servis.
+ * Graph of the served modules.
  *
- * Il repond a une seule question, mais la plus importante du developpement a
- * chaud : quand ce fichier change, que faut-il recharger ?
+ * It answers a single question, but the most important one in hot development:
+ * when this file changes, what has to be reloaded?
  *
  * @module
  */
-/** Un module connu du serveur. */
+/** A module known to the server. */
 interface ModuleNode {
-    /** Chemin absolu du fichier. */
+    /** Absolute path of the file. */
     readonly file: string;
-    /** URL sous laquelle le module est servi. */
+    /** URL the module is served under. */
     readonly url: string;
-    /** Modules qui importent celui-ci. */
+    /** Modules that import this one. */
     readonly importers: Set<string>;
-    /** Modules importes par celui-ci. */
+    /** Modules imported by this one. */
     readonly imported: Set<string>;
     /**
-     * `true` si le module declare accepter ses propres mises a jour via
+     * `true` when the module declares that it accepts its own updates through
      * `import.meta.hot.accept()`.
      */
     selfAccepting: boolean;
-    /** Code transforme, ou `undefined` si le module doit etre recompile. */
+    /** Transformed code, or `undefined` when the module must be rebuilt. */
     code: string | undefined;
-    /** Horodatage de la derniere invalidation, servant a casser le cache. */
+    /** Timestamp of the last invalidation, used to break the cache. */
     timestamp: number;
 }
 /**
- * Detecte si une source declare accepter ses propres mises a jour.
+ * Detects whether a source declares that it accepts its own updates.
  *
- * L'analyse est volontairement textuelle. Une analyse syntaxique complete
- * serait plus sure, mais `import.meta.hot.accept` est une formule trop
- * distinctive pour apparaitre par accident, et le cout d'un faux positif se
- * limite a une mise a jour la ou un rechargement aurait suffi.
+ * The analysis is deliberately textual. A full syntactic analysis would be
+ * safer, but `import.meta.hot.accept` is too distinctive a formula to appear by
+ * accident, and the cost of a false positive is limited to an update where a
+ * reload would have been enough.
  *
  * @example
  * detectSelfAccepting('import.meta.hot?.accept()') // true
  */
 declare function detectSelfAccepting(source: string): boolean;
-/** Graphe des modules et de leurs relations d'import. */
+/** Graph of the modules and of their import relations. */
 declare class ModuleGraph {
     private readonly nodes;
-    /** Recupere un module, ou le cree s'il est inconnu. */
+    /** Gets a module, or creates it when it is unknown. */
     ensure(file: string, url: string): ModuleNode;
-    /** Recupere un module deja connu. */
+    /** Gets a module already known. */
     get(file: string): ModuleNode | undefined;
-    /** Nombre de modules connus. */
+    /** Number of known modules. */
     get size(): number;
     /**
-     * Remplace la liste des dependances d'un module, en tenant a jour les
-     * relations inverses.
+     * Replaces the dependency list of a module, keeping the reverse relations up
+     * to date.
      */
     setDependencies(file: string, dependencies: readonly string[]): void;
     /**
-     * Invalide un module et remonte la chaine de ses importateurs jusqu'a
-     * trouver, sur chaque branche, un module qui accepte les mises a jour.
+     * Invalidates a module and climbs the chain of its importers until it finds,
+     * on every branch, a module that accepts updates.
      *
-     * @returns Les modules a recharger cote client. Un tableau vide signifie
-     *   qu'aucune frontiere n'accepte la mise a jour : il faut recharger la page.
+     * @returns The modules to reload on the client side. An empty array means
+     *   that no boundary accepts the update: the page must be reloaded.
      *
      * @example
-     * const boundaries = graph.invalidate('/projet/src/App.css')
+     * const boundaries = graph.invalidate('/project/src/App.css')
      */
     invalidate(file: string): ModuleNode[];
-    /** Oublie tous les modules. */
+    /** Forgets every module. */
     clear(): void;
 }
 
 /**
- * Transformation des modules servis en developpement.
+ * Transformation of the modules served in development.
  *
- * Le navigateur ne sait lire ni TypeScript, ni JSX, ni les specificateurs
- * d'import nus (`import React from 'react'`). Chaque module demande est donc
- * compile a la volee et ses imports sont reecrits en URL que le serveur sait
- * resoudre.
+ * The browser can read neither TypeScript, nor JSX, nor bare import specifiers
+ * (`import React from 'react'`). Every requested module is therefore compiled
+ * on the fly and its imports are rewritten into URLs the server knows how to
+ * resolve.
  *
- * La reecriture n'est pas faite a coups d'expressions regulieres — une chaine
- * de caracteres contenant le mot `import` suffirait a la mettre en defaut.
- * On s'appuie sur le resolveur du compilateur lui-meme : chaque import est
- * resolu puis **marque externe**, de sorte que rien n'est inline mais que tous
- * les chemins ressortent reecrits, avec la meme exactitude qu'une compilation
- * complete.
+ * The rewriting is not done with regular expressions — a string containing the
+ * word `import` would be enough to defeat it. We lean on the resolver of the
+ * bundler itself: every import is resolved then **marked external**, so that
+ * nothing is inlined but all the paths come out rewritten, with the same
+ * accuracy as a full build.
  *
  * @module
  */
 
 /**
- * Nom de fichier compile correspondant a un specificateur de dependance.
+ * Compiled file name matching a dependency specifier.
  *
- * Le nom est **aplati** : c'est ce qui rend l'URL servie exempte de segment de
- * dossier. Un module servi sous `/@deps/react-dom/client` resoudrait son propre
- * `import './chunk-X.js'` en `/@deps/react-dom/chunk-X.js`, alors que le
- * fragment est depose a la racine du cache.
+ * The name is **flattened**: that is what makes the served URL free of any
+ * directory segment. A module served under `/@deps/react-dom/client` would
+ * resolve its own `import './chunk-X.js'` to `/@deps/react-dom/chunk-X.js`,
+ * whereas the chunk is dropped at the root of the cache.
  *
  * @example
  * depFileName('react-dom/client') // 'react-dom_client.js'
- * depFileName('@scope/paquet')    // 'scope_paquet.js'
+ * depFileName('@scope/package')   // 'scope_package.js'
  */
 declare function depFileName(specifier: string): string;
 
 /**
- * Pre-compilation des dependances.
+ * Prebundling of the dependencies.
  *
- * Deux raisons la rendent indispensable, et non optionnelle :
+ * Two reasons make it indispensable, and not optional:
  *
- * 1. beaucoup de paquets ne sont encore distribues qu'en modules CommonJS, que
- *    le navigateur ne sait pas charger ;
- * 2. une dependance eclatee en centaines de petits fichiers declencherait
- *    autant de requetes au premier chargement.
+ * 1. many packages are still distributed only as CommonJS modules, which the
+ *    browser cannot load;
+ * 2. a dependency split into hundreds of small files would trigger as many
+ *    requests on the first load.
  *
- * Le piege, lui, est ailleurs : si `react` et `react-dom/client` etaient
- * compiles separement, chacun embarquerait sa copie de React. Deux instances
- * de React dans une meme page cassent les hooks et les contextes, avec des
- * symptomes deroutants. Tous les specificateurs sont donc **compiles en une
- * seule passe**, avec decoupage : le code commun se retrouve dans un fragment
- * partage, et l'instance reste unique.
+ * The trap lies elsewhere: if `react` and `react-dom/client` were bundled
+ * separately, each would carry its own copy of React. Two instances of React in
+ * the same page break hooks and contexts, with baffling symptoms. Every
+ * specifier is therefore **bundled in a single pass**, with splitting: the
+ * common code ends up in a shared chunk, and the instance stays unique.
  *
  * @module
  */
 
-/** Resultat de la pre-compilation. */
+/** Result of the prebundling. */
 interface OptimizedDeps {
-    /** Dossier contenant les modules compiles. */
+    /** Directory holding the bundled modules. */
     readonly directory: string;
-    /** Specificateurs disponibles. */
+    /** Specifiers available. */
     readonly specifiers: readonly string[];
-    /** `true` si une compilation a reellement eu lieu. */
+    /** `true` when a build actually took place. */
     readonly rebuilt: boolean;
 }
 /**
- * Parcourt le code du projet a la recherche des dependances reellement
- * importees, transitivement.
+ * Walks the project code looking for the dependencies actually imported,
+ * transitively.
  *
- * Se fonder sur le champ `dependencies` du manifeste ne suffirait pas : une
- * application importe `react-dom/client`, jamais `react-dom` tout court.
+ * Relying on the `dependencies` field of the manifest would not be enough: an
+ * application imports `react-dom/client`, never plain `react-dom`.
  *
- * @param entries Points d'entree du projet, en chemins absolus.
+ * @param entries Entry points of the project, as absolute paths.
  *
  * @example
- * const specifiers = await scanDependencies(config, ['/projet/src/main.tsx'])
+ * const specifiers = await scanDependencies(config, ['/project/src/main.tsx'])
  */
 declare function scanDependencies(config: ResolvedConfig, entries: readonly string[]): Promise<string[]>;
 /**
- * Compile un ensemble de specificateurs en une seule passe.
+ * Bundles a set of specifiers in a single pass.
  *
- * @param config Configuration resolue du projet.
- * @param specifiers Specificateurs a compiler.
- * @param force Recompile meme si le cache semble valide.
+ * @param config Resolved configuration of the project.
+ * @param specifiers Specifiers to bundle.
+ * @param force Rebuilds even when the cache looks valid.
  *
  * @example
  * const deps = await optimizeDeps(config, ['react', 'react-dom/client'])
  */
 declare function optimizeDeps(config: ResolvedConfig, specifiers: readonly string[], force?: boolean): Promise<OptimizedDeps>;
 
-export { type BuildConfig, type BuildOutput, type BuiltFile, type DevServer, ModuleGraph, type ModuleNode, type OdoroConfig, type OptimizedDeps, type PreviewServer, type ResolvedConfig, type ServerConfig, buildProject, defineConfig, depFileName, detectSelfAccepting, loadConfig, optimizeDeps, reportBuild, scanDependencies, startDevServer, startPreviewServer };
+export { type BuildConfig, type BuildOutput, type BuiltFile, type DevServer, type HtmlContext, type HttpsConfig, type LoadedEnv, type Manifest, type ManifestEntry, type Middleware, ModuleGraph, type ModuleNode, type OdoroConfig, type OdoroPlugin, type OptimizedDeps, type PrerenderConfig, type PrerenderOutput, type PreviewServer, type ResolvedBuild, type ResolvedConfig, type ResolvedPrerender, type RouteRender, type ServerConfig, type ServerContext, type TransformContext, buildManifest, buildProject, chunksFor, clientEnv, defineConfig, depFileName, detectSelfAccepting, hasGlob, loadConfig, loadEnv, optimizeDeps, prerender, reportBuild, scanDependencies, startDevServer, startPreviewServer, transformGlob };