toiljs 0.0.11 → 0.0.12

package/src/compiler/image-report.ts

@@ -1,85 +1,88 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-import pc from 'picocolors';
-import type { Logger, Plugin } from 'vite';
-
-/** Raster/vector outputs the image pipeline may emit. */
-const IMAGE_RE = /\.(png|jpe?g|webp|avif|gif|tiff|svg)$/i;
-
-/** Formats a byte count like Vite's asset table (kB, base 1000). */
-function kb(bytes: number): string {
-    return `${(bytes / 1000).toFixed(2)} kB`;
-}
-
-interface Variant {
-    readonly out: string;
-    readonly outSize: number;
-}
-
-/**
- * Build-only plugin that reports which imported images the pipeline optimized, each source image,
- * its emitted variant(s), and the size saved. `public/` assets (copied as-is) never enter the
- * bundle, so they don't appear here. Logs nothing when no images were processed.
- *
- * `viteRoot` is Vite's root (the `.toil` dir) that emitted assets' `originalFileNames` are relative
- * to; `projectRoot` is used only to print friendly source paths.
- */
-export function imageReportPlugin(projectRoot: string, viteRoot: string): Plugin {
-    let logger: Logger | undefined;
-    return {
-        name: 'toil:image-report',
-        apply: 'build',
-        configResolved(config) {
-            logger = config.logger;
-        },
-        writeBundle(_options, bundle) {
-            // Group emitted image assets by their source file.
-            const bySource = new Map<string, { label: string; inSize: number | null; variants: Variant[] }>();
-            for (const file of Object.values(bundle)) {
-                if (file.type !== 'asset' || !IMAGE_RE.test(file.fileName)) continue;
-                const source = file.originalFileNames[0];
-                const key = source ?? file.fileName;
-                const outSize =
-                    typeof file.source === 'string'
-                        ? Buffer.byteLength(file.source)
-                        : file.source.byteLength;
-
-                let entry = bySource.get(key);
-                if (!entry) {
-                    let inSize: number | null = null;
-                    let label = '(generated)';
-                    if (source !== undefined) {
-                        const abs = path.resolve(viteRoot, source);
-                        label = path.relative(projectRoot, abs);
-                        try {
-                            inSize = fs.statSync(abs).size;
-                        } catch {
-                            inSize = null;
-                        }
-                    }
-                    entry = { label, inSize, variants: [] };
-                    bySource.set(key, entry);
-                }
-                entry.variants.push({ out: file.fileName, outSize });
-            }
-
-            if (bySource.size === 0 || !logger) return;
-
-            const count = bySource.size;
-            logger.info('');
-            logger.info(pc.green(`  ✓ optimized ${String(count)} image${count === 1 ? '' : 's'}`));
-            for (const { label, inSize, variants } of bySource.values()) {
-                logger.info(`  ${pc.dim(label)}`);
-                for (const v of variants) {
-                    const saved =
-                        inSize && inSize > 0
-                            ? pc.green(`  -${String(Math.round((1 - v.outSize / inSize) * 100))}%`)
-                            : '';
-                    const from = inSize ? `${kb(inSize)} → ` : '';
-                    logger.info(`    ${pc.dim('→')} ${v.out}  ${from}${kb(v.outSize)}${saved}`);
-                }
-            }
-        },
-    };
-}
+import fs from 'node:fs';
+import path from 'node:path';
+
+import pc from 'picocolors';
+import type { Logger, Plugin } from 'vite';
+
+/** Raster/vector outputs the image pipeline may emit. */
+const IMAGE_RE = /\.(png|jpe?g|webp|avif|gif|tiff|svg)$/i;
+
+/** Formats a byte count like Vite's asset table (kB, base 1000). */
+function kb(bytes: number): string {
+    return `${(bytes / 1000).toFixed(2)} kB`;
+}
+
+interface Variant {
+    readonly out: string;
+    readonly outSize: number;
+}
+
+/**
+ * Build-only plugin that reports which imported images the pipeline optimized, each source image,
+ * its emitted variant(s), and the size saved. `public/` assets (copied as-is) never enter the
+ * bundle, so they don't appear here. Logs nothing when no images were processed.
+ *
+ * `viteRoot` is Vite's root (the `.toil` dir) that emitted assets' `originalFileNames` are relative
+ * to; `projectRoot` is used only to print friendly source paths.
+ */
+export function imageReportPlugin(projectRoot: string, viteRoot: string): Plugin {
+    let logger: Logger | undefined;
+    return {
+        name: 'toil:image-report',
+        apply: 'build',
+        configResolved(config) {
+            logger = config.logger;
+        },
+        writeBundle(_options, bundle) {
+            // Group emitted image assets by their source file.
+            const bySource = new Map<
+                string,
+                { label: string; inSize: number | null; variants: Variant[] }
+            >();
+            for (const file of Object.values(bundle)) {
+                if (file.type !== 'asset' || !IMAGE_RE.test(file.fileName)) continue;
+                const source = file.originalFileNames[0];
+                const key = source ?? file.fileName;
+                const outSize =
+                    typeof file.source === 'string'
+                        ? Buffer.byteLength(file.source)
+                        : file.source.byteLength;
+
+                let entry = bySource.get(key);
+                if (!entry) {
+                    let inSize: number | null = null;
+                    let label = '(generated)';
+                    if (source !== undefined) {
+                        const abs = path.resolve(viteRoot, source);
+                        label = path.relative(projectRoot, abs);
+                        try {
+                            inSize = fs.statSync(abs).size;
+                        } catch {
+                            inSize = null;
+                        }
+                    }
+                    entry = { label, inSize, variants: [] };
+                    bySource.set(key, entry);
+                }
+                entry.variants.push({ out: file.fileName, outSize });
+            }
+
+            if (bySource.size === 0 || !logger) return;
+
+            const count = bySource.size;
+            logger.info('');
+            logger.info(pc.green(`  ✓ optimized ${String(count)} image${count === 1 ? '' : 's'}`));
+            for (const { label, inSize, variants } of bySource.values()) {
+                logger.info(`  ${pc.dim(label)}`);
+                for (const v of variants) {
+                    const saved =
+                        inSize && inSize > 0
+                            ? pc.green(`  -${String(Math.round((1 - v.outSize / inSize) * 100))}%`)
+                            : '';
+                    const from = inSize ? `${kb(inSize)} → ` : '';
+                    logger.info(`    ${pc.dim('→')} ${v.out}  ${from}${kb(v.outSize)}${saved}`);
+                }
+            }
+        },
+    };
+}

package/src/compiler/index.ts

@@ -45,6 +45,8 @@ export async function start(opts: ToilCommandOptions = {}): Promise<RunningBacke
 }
 
 export { defineConfig, loadConfig } from './config.js';
+export { scanRoutes } from './routes.js';
+export type { ScannedRoute } from './routes.js';
 export { TOIL_ENV_DTS } from './generate.js';
 export { AI_HELPERS, AI_HELPER_IDS, aiHelperFiles, TOIL_DOCS } from './docs.js';
 export type { AiHelper } from './docs.js';

package/src/compiler/pages.ts

@@ -0,0 +1,70 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import type * as TS from 'typescript';
+
+import { extractStaticExports } from './prerender.js';
+import type { ScannedRoute } from './routes.js';
+
+type Ts = typeof TS;
+
+/**
+ * A page in the build-time search index: its URL pattern, whether it's dynamic, and the
+ * statically-extracted `metadata` literal (the searchable subset; dynamic `generateMetadata` and
+ * computed values can't be known at build, so they're absent). Serialized into the generated
+ * `routes` module and registered client-side for {@link searchPages}.
+ */
+export interface PageIndexEntry {
+    readonly path: string;
+    readonly dynamic: boolean;
+    readonly metadata: Record<string, unknown>;
+}
+
+/**
+ * Loads the project's TypeScript synchronously (so {@link buildPageIndex} can run inside the sync
+ * `generate()`), or `null` if it isn't installed — in which case pages are indexed by path only.
+ */
+function loadTypeScriptSync(root: string): Ts | null {
+    try {
+        const require = createRequire(path.join(root, 'package.json'));
+        const mod = require('typescript') as { default?: Ts } & Ts;
+        return mod.default ?? mod;
+    } catch {
+        return null;
+    }
+}
+
+/** True when a route pattern has dynamic (`:param` / `*catch-all`) segments. */
+function isDynamic(pattern: string): boolean {
+    return /[:*]/.test(pattern);
+}
+
+/**
+ * Builds the searchable page index from the scanned routes: every main-tree page (slots and
+ * intercepting routes are excluded — they don't own a distinct URL) paired with its statically
+ * extracted `metadata`. A route may also `export const searchHints` (a static `title`/`description`/
+ * `keywords` object) to feed the index even when its real metadata is dynamic (`generateMetadata`);
+ * hints are merged over the static `metadata`, winning ties. Reads each route file once.
+ */
+export function buildPageIndex(root: string, routes: readonly ScannedRoute[]): PageIndexEntry[] {
+    const ts = loadTypeScriptSync(root);
+    const seen = new Set<string>();
+    const pages: PageIndexEntry[] = [];
+    for (const route of routes) {
+        if (route.slot !== undefined || route.intercept) continue;
+        if (seen.has(route.pattern)) continue;
+        seen.add(route.pattern);
+        const exports = ts ? extractStaticExports(ts, route.file, ['metadata', 'searchHints']) : {};
+        const metadata = { ...exports.metadata, ...exports.searchHints };
+        pages.push({ path: route.pattern, dynamic: isDynamic(route.pattern), metadata });
+    }
+    // Stable order (by path) so the generated module is deterministic across runs.
+    pages.sort((a, b) => a.path.localeCompare(b.path));
+    return pages;
+}
+
+/** Serializes the page index to the `export const pages` literal embedded in the routes module. */
+export function pagesModuleSource(pages: readonly PageIndexEntry[]): string {
+    const body = pages.map((p) => `  ${JSON.stringify(p)},`).join('\n');
+    return `export const pages: PageMeta[] = [\n${body}\n];\n`;
+}

package/src/compiler/plugin.ts

@@ -1,47 +1,51 @@
-import { type Plugin } from 'vite';
-
-import { type ResolvedToilConfig } from './config.js';
-import { generate } from './generate.js';
-
-/**
- * Vite plugin that keeps the generated route table in sync during dev: when a route file is
- * added or removed, it regenerates `.toil/routes.ts` and triggers a full reload. Editing a
- * route file's contents hot-reloads through `@vitejs/plugin-react` as usual.
- */
-export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
-    return {
-        name: 'toil',
-        // Catch empty import specifiers in source and report the file, rolldown otherwise fails
-        // resolution with a cryptic "The specifiers must be a non-empty string. Received ''".
-        transform(code, id) {
-            const file = id.split('?')[0];
-            if (id.includes('\0') || file.includes('/node_modules/') || !/\.[mc]?[jt]sx?$/.test(file)) {
-                return null;
-            }
-            const empty =
-                /^[ \t]*import\s+(['"])\1\s*;?[ \t]*$/m.test(code) ||
-                /^[ \t]*import\b[^'"\n]*\bfrom\s+(['"])\1/m.test(code) ||
-                /^[ \t]*export\b[^'"\n]*\bfrom\s+(['"])\1/m.test(code) ||
-                /\bimport\s*\(\s*(['"])\1\s*\)/.test(code);
-            if (empty) {
-                throw new Error(
-                    `toil: empty import specifier (e.g. \`import '';\`) in ${file}, remove or complete the import.`,
-                );
-            }
-            return null;
-        },
-        configureServer(server) {
-            // Trailing slash so a sibling like `routes-extra/` doesn't match the `routes/` prefix.
-            const routesPrefix = cfg.routesAbsDir.replace(/\\/g, '/').replace(/\/?$/, '/');
-            const onChange = (file: string): void => {
-                if (file.replace(/\\/g, '/').startsWith(routesPrefix)) {
-                    generate(cfg);
-                    server.ws.send({ type: 'full-reload' });
-                }
-            };
-            server.watcher.add(cfg.routesAbsDir);
-            server.watcher.on('add', onChange);
-            server.watcher.on('unlink', onChange);
-        },
-    };
-}
+import { type Plugin } from 'vite';
+
+import { type ResolvedToilConfig } from './config.js';
+import { generate } from './generate.js';
+
+/**
+ * Vite plugin that keeps the generated route table in sync during dev: when a route file is
+ * added or removed, it regenerates `.toil/routes.ts` and triggers a full reload. Editing a
+ * route file's contents hot-reloads through `@vitejs/plugin-react` as usual.
+ */
+export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
+    return {
+        name: 'toil',
+        // Catch empty import specifiers in source and report the file, rolldown otherwise fails
+        // resolution with a cryptic "The specifiers must be a non-empty string. Received ''".
+        transform(code, id) {
+            const file = id.split('?')[0];
+            if (
+                id.includes('\0') ||
+                file.includes('/node_modules/') ||
+                !/\.[mc]?[jt]sx?$/.test(file)
+            ) {
+                return null;
+            }
+            const empty =
+                /^[ \t]*import\s+(['"])\1\s*;?[ \t]*$/m.test(code) ||
+                /^[ \t]*import\b[^'"\n]*\bfrom\s+(['"])\1/m.test(code) ||
+                /^[ \t]*export\b[^'"\n]*\bfrom\s+(['"])\1/m.test(code) ||
+                /\bimport\s*\(\s*(['"])\1\s*\)/.test(code);
+            if (empty) {
+                throw new Error(
+                    `toil: empty import specifier (e.g. \`import '';\`) in ${file}, remove or complete the import.`,
+                );
+            }
+            return null;
+        },
+        configureServer(server) {
+            // Trailing slash so a sibling like `routes-extra/` doesn't match the `routes/` prefix.
+            const routesPrefix = cfg.routesAbsDir.replace(/\\/g, '/').replace(/\/?$/, '/');
+            const onChange = (file: string): void => {
+                if (file.replace(/\\/g, '/').startsWith(routesPrefix)) {
+                    generate(cfg);
+                    server.ws.send({ type: 'full-reload' });
+                }
+            };
+            server.watcher.add(cfg.routesAbsDir);
+            server.watcher.on('add', onChange);
+            server.watcher.on('unlink', onChange);
+        },
+    };
+}

package/src/compiler/prerender.ts

@@ -1,130 +1,152 @@
-import { createRequire } from 'node:module';
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-import type * as TS from 'typescript';
-import type { Plugin } from 'vite';
-
-import { type ResolvedToilConfig } from './config.js';
-import { scanRoutes } from './routes.js';
-import { injectSeoHtml, routeSeo } from './seo.js';
-
-type Ts = typeof TS;
-
-/** Loads the project's TypeScript (used to read each route's static `metadata`), or `null` if absent. */
-async function loadTypeScript(root: string): Promise<Ts | null> {
-    try {
-        const resolved = createRequire(path.join(root, 'package.json')).resolve('typescript');
-        const mod = (await import(pathToFileURL(resolved).href)) as { default?: Ts } & Ts;
-        return mod.default ?? mod;
-    } catch {
-        return null;
-    }
-}
-
-/** Marks an AST node that isn't a static literal (so its value can't be baked at build). */
-const UNRESOLVED = Symbol('unresolved');
-
-/** Statically evaluates a literal expression node to a JS value, or `UNRESOLVED` if it isn't one. */
-function evalNode(ts: Ts, node: TS.Expression): unknown {
-    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
-    if (ts.isNumericLiteral(node)) return Number(node.text);
-    if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
-    if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
-    if (node.kind === ts.SyntaxKind.NullKeyword) return null;
-    if (ts.isArrayLiteralExpression(node)) {
-        const out: unknown[] = [];
-        for (const el of node.elements) {
-            const value = evalNode(ts, el);
-            if (value === UNRESOLVED) return UNRESOLVED;
-            out.push(value);
-        }
-        return out;
-    }
-    if (ts.isObjectLiteralExpression(node)) return evalObject(ts, node);
-    return UNRESOLVED;
-}
-
-/** Evaluates an object literal to a plain object, skipping any property that isn't a static literal. */
-function evalObject(ts: Ts, node: TS.ObjectLiteralExpression): Record<string, unknown> {
-    const obj: Record<string, unknown> = {};
-    for (const prop of node.properties) {
-        if (!ts.isPropertyAssignment(prop)) continue;
-        const key = ts.isIdentifier(prop.name)
-            ? prop.name.text
-            : ts.isStringLiteral(prop.name)
-              ? prop.name.text
-              : null;
-        if (key === null) continue;
-        const value = evalNode(ts, prop.initializer);
-        if (value !== UNRESOLVED) obj[key] = value;
-    }
-    return obj;
-}
-
-/**
- * Extracts a route's `export const metadata = { … }` if it's a static object literal, returning the
- * statically-evaluable subset (dynamic `generateMetadata` and computed values are skipped). `null`
- * when the file has no static metadata.
- */
-export function extractStaticMetadata(ts: Ts, filePath: string): Record<string, unknown> | null {
-    let source: string;
-    try {
-        source = fs.readFileSync(filePath, 'utf8');
-    } catch {
-        return null;
-    }
-    const sf = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-    for (const stmt of sf.statements) {
-        if (!ts.isVariableStatement(stmt)) continue;
-        if (!stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
-        for (const decl of stmt.declarationList.declarations) {
-            if (
-                ts.isIdentifier(decl.name) &&
-                decl.name.text === 'metadata' &&
-                decl.initializer &&
-                ts.isObjectLiteralExpression(decl.initializer)
-            ) {
-                return evalObject(ts, decl.initializer);
-            }
-        }
-    }
-    return null;
-}
-
-/**
- * Build-only plugin that statically pre-renders per-route HTML for SEO. After the bundle is written,
- * it takes the built shell (`index.html`), and for each static route bakes that route's
- * `metadata` (merged over the site-wide `seo` defaults) into a `<route>/index.html` so a JS-less
- * crawler hitting the route gets correct per-page tags. Dynamic (`generateMetadata`) and `:param`
- * routes are skipped (no data at build) and fall back to the client-rendered shell.
- */
-export function prerenderPlugin(cfg: ResolvedToilConfig): Plugin {
-    return {
-        name: 'toil:prerender-seo',
-        apply: 'build',
-        async closeBundle() {
-            if (!cfg.seo) return;
-            const outDir = path.resolve(cfg.root, cfg.outDir);
-            const shellPath = path.join(outDir, 'index.html');
-            if (!fs.existsSync(shellPath)) return;
-            const shell = fs.readFileSync(shellPath, 'utf8');
-            const ts = await loadTypeScript(cfg.root);
-
-            const routes = scanRoutes(cfg.routesAbsDir).filter(
-                (r) => r.slot === undefined && !r.intercept && !/[:*]/.test(r.pattern),
-            );
-            for (const route of routes) {
-                const metadata = ts ? extractStaticMetadata(ts, route.file) : null;
-                const html = injectSeoHtml(shell, routeSeo(cfg.seo, metadata, route.pattern));
-                const target =
-                    route.pattern === '/'
-                        ? shellPath
-                        : path.join(outDir, route.pattern.replace(/^\//, ''), 'index.html');
-                fs.mkdirSync(path.dirname(target), { recursive: true });
-                fs.writeFileSync(target, html);
-            }
-        },
-    };
-}
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type * as TS from 'typescript';
+import type { Plugin } from 'vite';
+
+import { type ResolvedToilConfig } from './config.js';
+import { scanRoutes } from './routes.js';
+import { injectSeoHtml, routeSeo } from './seo.js';
+
+type Ts = typeof TS;
+
+/** Loads the project's TypeScript (used to read each route's static `metadata`), or `null` if absent. */
+async function loadTypeScript(root: string): Promise<Ts | null> {
+    try {
+        const resolved = createRequire(path.join(root, 'package.json')).resolve('typescript');
+        const mod = (await import(pathToFileURL(resolved).href)) as { default?: Ts } & Ts;
+        return mod.default ?? mod;
+    } catch {
+        return null;
+    }
+}
+
+/** Marks an AST node that isn't a static literal (so its value can't be baked at build). */
+const UNRESOLVED = Symbol('unresolved');
+
+/** Statically evaluates a literal expression node to a JS value, or `UNRESOLVED` if it isn't one. */
+function evalNode(ts: Ts, node: TS.Expression): unknown {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+    if (ts.isNumericLiteral(node)) return Number(node.text);
+    if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+    if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+    if (ts.isArrayLiteralExpression(node)) {
+        const out: unknown[] = [];
+        for (const el of node.elements) {
+            const value = evalNode(ts, el);
+            if (value === UNRESOLVED) return UNRESOLVED;
+            out.push(value);
+        }
+        return out;
+    }
+    if (ts.isObjectLiteralExpression(node)) return evalObject(ts, node);
+    return UNRESOLVED;
+}
+
+/** Evaluates an object literal to a plain object, skipping any property that isn't a static literal. */
+function evalObject(ts: Ts, node: TS.ObjectLiteralExpression): Record<string, unknown> {
+    const obj: Record<string, unknown> = {};
+    for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const key = ts.isIdentifier(prop.name)
+            ? prop.name.text
+            : ts.isStringLiteral(prop.name)
+              ? prop.name.text
+              : null;
+        if (key === null) continue;
+        const value = evalNode(ts, prop.initializer);
+        if (value !== UNRESOLVED) obj[key] = value;
+    }
+    return obj;
+}
+
+/**
+ * Extracts the named `export const <name> = { … }` object-literal exports from a route file in a
+ * single parse, returning the statically-evaluable subset of each (dynamic and computed values are
+ * skipped). Names that are absent or not object literals are omitted from the result.
+ */
+export function extractStaticExports(
+    ts: Ts,
+    filePath: string,
+    names: readonly string[],
+): Record<string, Record<string, unknown>> {
+    let source: string;
+    try {
+        source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+        return {};
+    }
+    const wanted = new Set(names);
+    const out: Record<string, Record<string, unknown>> = {};
+    const sf = ts.createSourceFile(
+        filePath,
+        source,
+        ts.ScriptTarget.Latest,
+        true,
+        ts.ScriptKind.TSX,
+    );
+    for (const stmt of sf.statements) {
+        if (!ts.isVariableStatement(stmt)) continue;
+        if (!stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+        for (const decl of stmt.declarationList.declarations) {
+            if (
+                ts.isIdentifier(decl.name) &&
+                wanted.has(decl.name.text) &&
+                !(decl.name.text in out) &&
+                decl.initializer &&
+                ts.isObjectLiteralExpression(decl.initializer)
+            ) {
+                out[decl.name.text] = evalObject(ts, decl.initializer);
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * Extracts a route's `export const metadata = { … }` if it's a static object literal, returning the
+ * statically-evaluable subset (dynamic `generateMetadata` and computed values are skipped). `null`
+ * when the file has no static metadata.
+ */
+export function extractStaticMetadata(ts: Ts, filePath: string): Record<string, unknown> | null {
+    return extractStaticExports(ts, filePath, ['metadata']).metadata ?? null;
+}
+
+/**
+ * Build-only plugin that statically pre-renders per-route HTML for SEO. After the bundle is written,
+ * it takes the built shell (`index.html`), and for each static route bakes that route's
+ * `metadata` (merged over the site-wide `seo` defaults) into a `<route>/index.html` so a JS-less
+ * crawler hitting the route gets correct per-page tags. Dynamic (`generateMetadata`) and `:param`
+ * routes are skipped (no data at build) and fall back to the client-rendered shell.
+ */
+export function prerenderPlugin(cfg: ResolvedToilConfig): Plugin {
+    return {
+        name: 'toil:prerender-seo',
+        apply: 'build',
+        async closeBundle() {
+            if (!cfg.seo) return;
+            const outDir = path.resolve(cfg.root, cfg.outDir);
+            const shellPath = path.join(outDir, 'index.html');
+            if (!fs.existsSync(shellPath)) return;
+            const shell = fs.readFileSync(shellPath, 'utf8');
+            const ts = await loadTypeScript(cfg.root);
+
+            const routes = scanRoutes(cfg.routesAbsDir).filter(
+                (r) => r.slot === undefined && !r.intercept && !/[:*]/.test(r.pattern),
+            );
+            for (const route of routes) {
+                const metadata = ts ? extractStaticMetadata(ts, route.file) : null;
+                const html = injectSeoHtml(shell, routeSeo(cfg.seo, metadata, route.pattern));
+                const target =
+                    route.pattern === '/'
+                        ? shellPath
+                        : path.join(outDir, route.pattern.replace(/^\//, ''), 'index.html');
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                fs.writeFileSync(target, html);
+            }
+        },
+    };
+}