@timber-js/app 0.2.0-alpha.181 → 0.2.0-alpha.183

package/src/plugins/static-build.ts

@@ -3,13 +3,24 @@
  *
  * When `output: 'static'` is set in timber.config.ts, this plugin:
  * 1. Validates that no dynamic APIs (getCookies(), getHeaders()) are used
- * 2. Coordinates build-time rendering of all pages
+ * 2. After the build, renders all routes to static HTML + RSC flight files
  *
- * Design doc: design/15-future-prerendering.md
+ * Design doc: design/11-platform.md §"static output mode"
  */
 
 import type { Plugin } from 'vite';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile, rename } from 'node:fs/promises';
+import { dirname, extname, join, resolve, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import type { PluginContext } from '../plugin-context.js';
+import type {
+  StaticGenerationOptions,
+  StaticGenerationSummary,
+  StaticPageEntry,
+  StaticRedirectEntry,
+} from '../server/static-generator.js';
+import { mergeRscAssetsManifest } from './adapter-build.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -74,6 +85,237 @@ export function detectDynamicApis(code: string, fileId: string): StaticValidatio
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// Redirect rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a `_redirects` file from collected redirect entries.
+ * Uses the Cloudflare Pages / Netlify format: `/from /to statusCode`
+ *
+ * @internal Exported for testing.
+ */
+export function generateRedirectsFile(redirects: StaticRedirectEntry[]): string {
+  const lines = redirects.map((r) => `${r.from} ${r.to} ${r.status}`);
+  return lines.join('\n') + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// File output helpers
+// ---------------------------------------------------------------------------
+
+/** Write a file atomically: temp sibling + rename. */
+async function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void> {
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, data);
+  await rename(tmp, path);
+}
+
+/**
+ * Determine the output file path for a static page entry.
+ *
+ * Pages: /about → about/index.html, / → index.html
+ * RSC:   /about → _rsc/about.rsc, / → _rsc/index.rsc
+ * API:   /feed.xml → feed.xml, /api/data → api/data
+ */
+export function staticOutputPath(entry: StaticPageEntry): string {
+  const urlPath = entry.urlPath === '/' ? '' : entry.urlPath;
+
+  if (entry.kind === 'rsc') {
+    const rscPath = urlPath || '/index';
+    return `_rsc${rscPath}.rsc`;
+  }
+
+  if (entry.kind === 'api') {
+    // API routes use their URL path directly. If no extension, fall
+    // back to the path as-is (static host serves based on content type).
+    return urlPath.startsWith('/') ? urlPath.slice(1) : urlPath || 'index';
+  }
+
+  // HTML pages
+  if (!urlPath) return 'index.html';
+  // Synthetic 404 entry from static generation — must be 404.html at the
+  // root so static hosts (GitHub Pages, Cloudflare Pages, Netlify) serve
+  // it automatically for unmatched URLs. Uses an internal urlPath to avoid
+  // colliding with a real /404 page route.
+  if (urlPath === '/_timber_not_found') return '404.html';
+  return `${urlPath.startsWith('/') ? urlPath.slice(1) : urlPath}/index.html`;
+}
+
+// ---------------------------------------------------------------------------
+// Static generation orchestration (runs after Vite build)
+// ---------------------------------------------------------------------------
+
+interface StaticGenerateModule {
+  __timber_generateStaticSite?: (
+    options: StaticGenerationOptions
+  ) => Promise<StaticGenerationSummary>;
+}
+
+/**
+ * Load the built RSC entry and run the static generation pass.
+ *
+ * Unlike prebuilt capture, this needs the FULL pipeline handler, so
+ * __TIMBER_CAPTURE_MODE__ must be false.
+ */
+async function runStaticGeneration(ctx: PluginContext): Promise<StaticGenerationSummary> {
+  const entryPath = join(ctx.buildDir, 'rsc', 'index.js');
+  if (!existsSync(entryPath)) {
+    throw new Error(
+      `[timber] Static generation: built RSC entry not found at ${entryPath} — ` +
+        `the build output is missing`
+    );
+  }
+
+  const g = globalThis as Record<string, unknown>;
+
+  // Set up the build manifest (same as adapter-build and prebuilt-capture).
+  if (ctx.buildManifest) g.__TIMBER_BUILD_MANIFEST__ ??= ctx.buildManifest;
+  if (ctx.deploymentId) g.__TIMBER_DEPLOYMENT_ID__ ??= ctx.deploymentId;
+
+  // Ensure capture mode is off — we need the full handler.
+  g.__TIMBER_CAPTURE_MODE__ = false;
+
+  // Merge per-route CSS and modulepreload entries from the RSC assets
+  // manifest into the build manifest BEFORE rendering, so rendered HTML
+  // includes all <link> tags. This same merge normally runs in
+  // adapter-build, but static generation runs first.
+  if (ctx.buildManifest) {
+    await mergeRscAssetsManifest(ctx.buildDir, ctx.root, ctx.buildManifest, ctx.routeClientRefKeys);
+  }
+
+  console.log('[timber] Static generation: building site…');
+
+  let mod: StaticGenerateModule;
+  try {
+    const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
+    mod = (await import(/* @vite-ignore */ entryUrl)) as StaticGenerateModule;
+  } catch (error) {
+    throw new Error(
+      `[timber] Static generation: failed to load the built RSC entry (${entryPath}). ` +
+        `The full request handler must initialize for static rendering.`,
+      { cause: error }
+    );
+  }
+
+  const generate = mod.__timber_generateStaticSite;
+  if (typeof generate !== 'function') {
+    throw new Error(
+      `[timber] Static generation: built RSC entry does not export ` +
+        `__timber_generateStaticSite — rebuild from a clean build directory`
+    );
+  }
+
+  const staticDir = join(ctx.buildDir, 'static-pages');
+  await mkdir(staticDir, { recursive: true });
+
+  const sitemapConfig = ctx.config.sitemap;
+  const autoSitemapEnabled = Boolean(sitemapConfig?.enabled && sitemapConfig?.baseUrl);
+
+  const contentTypes: Record<string, string> = {};
+
+  const summary = await generate({
+    autoSitemapEnabled,
+    renderTimeoutMs: ctx.config.renderTimeoutMs,
+    onEntry: async (entry: StaticPageEntry) => {
+      const relPath = staticOutputPath(entry);
+      const fullPath = resolve(staticDir, relPath);
+
+      // Reject path traversal: generated params with "../" could escape
+      // the output directory and overwrite build artifacts.
+      const rel = relative(staticDir, fullPath);
+      if (rel.startsWith('..') || resolve(staticDir, rel) !== fullPath) {
+        throw new Error(
+          `[timber] Static generation: output path "${relPath}" escapes the ` +
+            `static output directory — check generateStaticSegmentParams for ` +
+            `path traversal characters in ${entry.urlPath}`
+        );
+      }
+
+      await mkdir(dirname(fullPath), { recursive: true });
+      await writeFileAtomic(fullPath, entry.body);
+
+      // Write params sidecar for RSC entries with route params.
+      // Static .rsc files don't carry HTTP headers, so the client
+      // fetches this sidecar to populate useSegmentParams(). TIM-1246.
+      if (entry.kind === 'rsc' && entry.headers['x-timber-params']) {
+        const paramsPath = fullPath.replace(/\.rsc$/, '.params.json');
+        await writeFileAtomic(paramsPath, entry.headers['x-timber-params']);
+      }
+
+      // Track Content-Type for extensionless API routes so adapters
+      // can write per-path Content-Type rules in _headers. TIM-1241.
+      if (entry.kind === 'api' && !extname(relPath) && entry.contentType) {
+        contentTypes[entry.urlPath] = entry.contentType;
+      }
+    },
+  });
+
+  const totalUrls = summary.rendered + summary.errors.length;
+  console.log(
+    `[timber] Static generation: rendered ${summary.rendered}/${totalUrls} entries.` +
+      (summary.errors.length > 0 ? ` ${summary.errors.length} failed.` : '') +
+      (summary.redirects.length > 0 ? ` ${summary.redirects.length} redirect(s).` : '')
+  );
+
+  if (summary.errors.length > 0) {
+    const details = summary.errors.map((e) => `  - ${e.urlPath}: ${e.message}`).join('\n');
+    throw new Error(`[timber] Static generation failed:\n${details}`);
+  }
+
+  // Store content-type mappings on the plugin context so adapters
+  // can include them in the _headers file. TIM-1241.
+  if (Object.keys(contentTypes).length > 0) {
+    ctx.staticContentTypes = contentTypes;
+  }
+
+  // Write _redirects file for platform redirect rules (Cloudflare Pages,
+  // Netlify, etc.). Format: /from /to status. See TIM-1245.
+  if (summary.redirects.length > 0) {
+    const generated = generateRedirectsFile(summary.redirects);
+    const redirectsPath = join(staticDir, '_redirects');
+
+    // Merge with user-authored _redirects if present. TIM-1249.
+    const userRedirects = await readUserRedirects(ctx.root);
+    if (userRedirects !== null) {
+      await writeFileAtomic(redirectsPath, generated + '\n' + userRedirects);
+      console.log(
+        `[timber] Static generation: wrote _redirects with ${summary.redirects.length} ` +
+          `generated rule(s), merged with user-authored _redirects`
+      );
+    } else {
+      await writeFileAtomic(redirectsPath, generated);
+      console.log(
+        `[timber] Static generation: wrote _redirects with ${summary.redirects.length} rule(s)`
+      );
+    }
+  }
+
+  return summary;
+}
+
+// ---------------------------------------------------------------------------
+// User-authored _redirects merge (TIM-1249)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a user-authored `_redirects` file from the project's `public/`
+ * directory. Returns `null` if no file exists.
+ *
+ * @internal Exported for testing.
+ */
+export async function readUserRedirects(root: string): Promise<string | null> {
+  const candidates = [join(root, 'public', '_redirects')];
+  for (const path of candidates) {
+    try {
+      return await readFile(path, 'utf-8');
+    } catch {
+      // File doesn't exist — try next
+    }
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Vite Plugin
 // ---------------------------------------------------------------------------
@@ -85,6 +327,7 @@ export function detectDynamicApis(code: string, fileId: string): StaticValidatio
  *
  * Hooks:
  * - transform: Validates source files for static mode violations
+ * - buildApp (post): Renders all routes to static HTML after the build
  */
 export function timberStaticBuild(ctx: PluginContext): Plugin {
   return {
@@ -128,5 +371,24 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
 
       return null;
     },
+
+    /**
+     * After all environments are built, render every route to static HTML.
+     *
+     * Runs with order: 'post' so the RSC plugin's buildApp completes first,
+     * producing the built entry we import. Must run BEFORE the adapter
+     * build copies output to its platform-specific directory.
+     */
+    buildApp: {
+      order: 'post' as const,
+      async handler() {
+        if (ctx.dev) return;
+
+        const isStatic = ctx.config.output === 'static';
+        if (!isStatic) return;
+
+        await runStaticGeneration(ctx);
+      },
+    },
   };
 }

package/src/server/rsc-entry/index.ts

@@ -69,6 +69,7 @@ import { capturePrebuiltPayloads } from '../prebuilt-builder.js';
 import { setPrebuiltPayloadSource } from '../prebuilt/payload-source.js';
 import { setRscFunctions, setComponentRefreshTimeout } from '../prebuilt-runtime.js';
 import { createAutoSitemapHandler } from '../sitemap-handler.js';
+import { generateStaticSite } from '../static-generator.js';
 
 /**
  * Resolve the Server-Timing mode from timber.config.ts.
@@ -461,6 +462,29 @@ export function __timber_capturePrebuilt(
   return capturePrebuiltPayloads(routeManifest, options);
 }
 
+/**
+ * Post-build static site generation entry point (TIM-1238). Renders every
+ * route in the manifest to HTML + RSC flight payloads. Must run inside the
+ * built RSC bundle — the handler, route manifest, and page module loaders
+ * are module instances in THIS bundle's graph.
+ *
+ * Unlike capture mode, this needs the full pipeline handler, so it must
+ * NOT run when __TIMBER_CAPTURE_MODE__ is set.
+ *
+ * See design/11-platform.md §"static output mode".
+ */
+export function __timber_generateStaticSite(
+  options: import('../static-generator.js').StaticGenerationOptions
+): Promise<import('../static-generator.js').StaticGenerationSummary> {
+  if (!_handler) {
+    throw new Error(
+      '[timber] __timber_generateStaticSite requires the full request handler. ' +
+        'Do not call in capture mode (__TIMBER_CAPTURE_MODE__).'
+    );
+  }
+  return generateStaticSite(routeManifest, _handler, options);
+}
+
 // Schema codecs are needed by both the capture path (param coercion) and
 // the request handler, so register them unconditionally.
 setGlobalSchemaCodecs(globalSchemaCodecs);

package/src/server/sitemap-generator.ts

@@ -339,7 +339,7 @@ export async function generateSitemap(
  * When a user-authored sitemap exists at the root, auto-generation is disabled
  * to avoid conflicts — the user takes full control.
  */
-export function hasUserSitemap(root: SegmentNode): boolean {
+export function hasUserSitemap(root: SegmentNode<unknown>): boolean {
   if (!root.metadataRoutes) return false;
   return 'sitemap' in root.metadataRoutes;
 }