@timber-js/app 0.1.1 → 0.1.3

package/src/plugins/mdx.ts

@@ -0,0 +1,179 @@
+/**
+ * timber-mdx — Vite sub-plugin for MDX page rendering.
+ *
+ * Wires @mdx-js/rollup into the Vite pipeline when MDX is activated.
+ * MDX is activated when pageExtensions includes 'mdx' or 'md', or
+ * when a content/ directory exists at the project root.
+ *
+ * Design doc: 20-content-collections.md §"The timber-mdx Plugin"
+ */
+
+import type { Plugin } from 'vite';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { PluginContext } from '#/index.js';
+
+const MDX_EXTENSIONS = ['mdx', 'md'];
+
+/**
+ * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root.
+ * Returns the absolute path if found, otherwise undefined.
+ */
+function findMdxComponents(root: string): string | undefined {
+  const candidates = [
+    'mdx-components.tsx',
+    'mdx-components.ts',
+    'mdx-components.jsx',
+    'mdx-components.js',
+  ];
+  for (const name of candidates) {
+    const p = join(root, name);
+    if (existsSync(p)) return p;
+  }
+  return undefined;
+}
+
+/**
+ * Determine if MDX should be activated based on config and project structure.
+ */
+function shouldActivate(ctx: PluginContext): boolean {
+  const exts = ctx.config.pageExtensions;
+  if (exts && exts.some((ext) => MDX_EXTENSIONS.includes(ext))) {
+    return true;
+  }
+
+  if (existsSync(join(ctx.root, 'content'))) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Try to dynamically import a module by name. Returns the default export
+ * or the module itself, or undefined if the module is not installed.
+ */
+async function tryImport(name: string): Promise<unknown | undefined> {
+  try {
+    const mod = await import(name);
+    return mod.default ?? mod;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Create the timber-mdx Vite plugin.
+ *
+ * Uses the transform and resolveId hooks to delegate MDX compilation
+ * to @mdx-js/rollup. The inner plugin is loaded lazily on first activation.
+ *
+ * Hooks: buildStart (loads @mdx-js/rollup), resolveId, load, transform
+ */
+export function timberMdx(ctx: PluginContext): Plugin {
+  let innerPlugin: Plugin | null = null;
+
+  async function activate(): Promise<void> {
+    if (innerPlugin !== null || !shouldActivate(ctx)) return;
+
+    const createMdxPlugin = (await tryImport('@mdx-js/rollup')) as
+      | ((options?: Record<string, unknown>) => Plugin)
+      | undefined;
+
+    if (!createMdxPlugin) {
+      throw new Error(
+        [
+          '[timber] MDX is enabled but @mdx-js/rollup is not installed.',
+          '',
+          'Install it:',
+          '  pnpm add -D @mdx-js/rollup remark-frontmatter remark-mdx-frontmatter',
+          '',
+          'MDX is activated because pageExtensions includes "mdx"/"md" or a content/ directory exists.',
+        ].join('\n')
+      );
+    }
+
+    const mdxConfig = ctx.config.mdx ?? {};
+
+    // Auto-register frontmatter plugins
+    const remarkPlugins: unknown[] = [];
+    const remarkFrontmatter = await tryImport('remark-frontmatter');
+    const remarkMdxFrontmatter = await tryImport('remark-mdx-frontmatter');
+    if (remarkFrontmatter) remarkPlugins.push(remarkFrontmatter);
+    if (remarkMdxFrontmatter) remarkPlugins.push(remarkMdxFrontmatter);
+
+    if (mdxConfig.remarkPlugins) {
+      remarkPlugins.push(...mdxConfig.remarkPlugins);
+    }
+
+    const mdxOptions: Record<string, unknown> = {
+      remarkPlugins,
+      rehypePlugins: mdxConfig.rehypePlugins ?? [],
+      recmaPlugins: mdxConfig.recmaPlugins ?? [],
+      remarkRehypeOptions: mdxConfig.remarkRehypeOptions,
+    };
+
+    const mdxComponentsPath = findMdxComponents(ctx.root);
+    if (mdxComponentsPath) {
+      mdxOptions.providerImportSource = mdxComponentsPath;
+    }
+
+    innerPlugin = createMdxPlugin(mdxOptions);
+  }
+
+  return {
+    name: 'timber-mdx',
+    // Must run before @vitejs/plugin-rsc (rsc:use-client) which tries to parse
+    // all files as JS. MDX files must be compiled to JS first.
+    enforce: 'pre',
+
+    async buildStart(options) {
+      ctx.timer.start('mdx-activate');
+      await activate();
+      ctx.timer.end('mdx-activate');
+      if (!innerPlugin) return;
+      if (typeof innerPlugin.buildStart === 'function') {
+        await (innerPlugin.buildStart as (options: unknown) => void | Promise<void>).call(
+          this,
+          options
+        );
+      }
+    },
+
+    async resolveId(source, importer, options) {
+      if (!innerPlugin) return null;
+      // MDX pages are server components — only compile in the RSC environment.
+      // This prevents server-only deps (e.g. bright via mdx-components) from
+      // being pulled into SSR or client bundles.
+      const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+      if (envName && envName !== 'rsc') return null;
+      if (typeof innerPlugin.resolveId === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (innerPlugin.resolveId as any).call(this, source, importer, options);
+      }
+      return null;
+    },
+
+    async load(id) {
+      if (!innerPlugin) return null;
+      const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+      if (envName && envName !== 'rsc') return null;
+      if (typeof innerPlugin.load === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (innerPlugin.load as any).call(this, id);
+      }
+      return null;
+    },
+
+    async transform(code, id) {
+      if (!innerPlugin) return null;
+      const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+      if (envName && envName !== 'rsc') return null;
+      if (typeof innerPlugin.transform === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (innerPlugin.transform as any).call(this, code, id);
+      }
+      return null;
+    },
+  };
+}

package/src/plugins/react-prod.ts

@@ -0,0 +1,56 @@
+import type { Plugin } from 'vite';
+
+/**
+ * Redirect React's CJS development bundles to production bundles.
+ *
+ * React packages use a runtime `process.env.NODE_ENV` check in their CJS
+ * entry points to conditionally require either `*.development.js` or
+ * `*.production.js`. Rollup's CJS plugin resolves both branches statically
+ * before the `define` replacement can eliminate the dead branch, causing
+ * development React code to be included in production builds.
+ *
+ * This plugin intercepts `resolveId` and rewrites any `*.development.js`
+ * import under `react/cjs/`, `react-dom/cjs/`, or `scheduler/cjs/` to
+ * its `*.production.js` counterpart.
+ *
+ * Only active in production builds. Has no effect in dev mode.
+ */
+export function timberReactProd(): Plugin {
+  let isProd = false;
+
+  return {
+    name: 'timber-react-prod',
+    enforce: 'pre',
+    configResolved(config) {
+      isProd = config.command === 'build' && config.mode === 'production';
+    },
+    resolveId: {
+      order: 'pre',
+      async handler(source, importer, options) {
+        if (!isProd) return;
+
+        // Match: react/cjs/*.development.js, react-dom/cjs/*.development.js, scheduler/cjs/*.development.js
+        if (!source.includes('.development.')) return;
+
+        const resolved = await this.resolve(source, importer, {
+          ...options,
+          skipSelf: true,
+        });
+        if (!resolved) return;
+
+        // Only rewrite paths inside react/react-dom/scheduler/react-server-dom CJS directories
+        if (
+          !resolved.id.includes('/react/cjs/') &&
+          !resolved.id.includes('/react-dom/cjs/') &&
+          !resolved.id.includes('/scheduler/cjs/') &&
+          !resolved.id.includes('/react-server-dom/cjs/')
+        ) {
+          return;
+        }
+
+        const prodId = resolved.id.replace('.development.', '.production.');
+        return { ...resolved, id: prodId };
+      },
+    },
+  };
+}

package/src/plugins/routing.ts

@@ -0,0 +1,419 @@
+/**
+ * timber-routing — Vite sub-plugin for route manifest generation.
+ *
+ * Bridges the route scanner with Vite's module graph. Scans app/ at startup,
+ * watches for file changes in dev, and serves the virtual:timber-route-manifest
+ * module that entry files consume.
+ *
+ * Design docs: 18-build-system.md §"Virtual Modules", 07-routing.md
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { scanRoutes } from '#/routing/scanner.js';
+import { generateRouteMap } from '#/routing/codegen.js';
+import { collectInterceptionRewrites } from '#/routing/interception.js';
+import { lintStatusFileDirectives, formatStatusFileLintWarnings } from '#/routing/status-file-lint.js';
+import type { RouteTree, SegmentNode, RouteFile } from '#/routing/types.js';
+import type { PluginContext } from '#/index.js';
+
+const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
+const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
+
+/**
+ * File convention names we track for changes that require manifest regeneration.
+ */
+const ROUTE_FILE_PATTERNS =
+  /\/(page|layout|middleware|access|route|error|default|denied|search-params|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
+
+/**
+ * Create the timber-routing Vite plugin.
+ *
+ * Hooks: resolveId, load, buildStart, configureServer
+ */
+/** Absolute path to the generated route map declaration file. */
+const CODEGEN_OUTPUT = '.timber/timber-routes.d.ts';
+
+/**
+ * Content of the timber-env.d.ts file written to the project root.
+ *
+ * Uses a triple-slash reference so TypeScript auto-discovers the generated
+ * route map without the user needing to edit tsconfig.json — same pattern
+ * as Next.js's next-env.d.ts.
+ */
+const TIMBER_ENV_DTS = [
+  '// This file is auto-generated by timber.js. Do not edit.',
+  '// It ensures TypeScript picks up the generated route types.',
+  '// eslint-disable-next-line @typescript-eslint/triple-slash-reference',
+  '/// <reference path=".timber/timber-routes.d.ts" />',
+  '',
+].join('\n');
+
+/**
+ * Write the generated route map and the timber-env.d.ts reference file.
+ *
+ * Fire-and-forget — never awaited to avoid blocking the hot path.
+ * Errors are swallowed; a missing .d.ts is a developer UX issue, not a runtime failure.
+ */
+function writeCodegen(ctx: PluginContext): void {
+  if (!ctx.routeTree) return;
+  const timberDir = join(ctx.root, '.timber');
+  const content = generateRouteMap(ctx.routeTree, { appDir: ctx.appDir, outputDir: timberDir });
+  const routesPath = join(ctx.root, CODEGEN_OUTPUT);
+  const envPath = join(ctx.root, 'timber-env.d.ts');
+  mkdir(timberDir, { recursive: true })
+    .then(() =>
+      Promise.all([
+        writeFile(routesPath, content, 'utf-8'),
+        writeFile(envPath, TIMBER_ENV_DTS, 'utf-8'),
+      ])
+    )
+    .catch((err) => {
+      // Non-fatal — types are a dev convenience, but log so issues are visible
+      console.warn('[timber] Failed to write codegen output:', err);
+    });
+}
+
+export function timberRouting(ctx: PluginContext): Plugin {
+  /** Track warned files to avoid repeating warnings on rescan. */
+  const warnedFiles = new Set<string>();
+
+  function rescan(): void {
+    ctx.timer.start('route-scan');
+    ctx.routeTree = scanRoutes(ctx.appDir, {
+      pageExtensions: ctx.config.pageExtensions,
+    });
+    ctx.timer.end('route-scan');
+    writeCodegen(ctx);
+
+    // Lint status files for missing 'use client' directive
+    const warnings = lintStatusFileDirectives(ctx.routeTree);
+    const newWarnings = warnings.filter((w) => !warnedFiles.has(w.filePath));
+    if (newWarnings.length > 0) {
+      for (const w of newWarnings) warnedFiles.add(w.filePath);
+      console.warn(formatStatusFileLintWarnings(newWarnings));
+    }
+  }
+
+  return {
+    name: 'timber-routing',
+
+    /**
+     * Resolve the virtual module ID.
+     *
+     * Handles:
+     * - virtual:timber-route-manifest
+     * - <root>/virtual:timber-route-manifest (Vite SSR build root prefix)
+     * - \0virtual:timber-route-manifest (RSC plugin re-imports)
+     */
+    resolveId(id: string) {
+      // Strip \0 prefix if present (RSC plugin generates these)
+      const cleanId = id.startsWith('\0') ? id.slice(1) : id;
+
+      if (cleanId === VIRTUAL_MODULE_ID) {
+        return RESOLVED_VIRTUAL_ID;
+      }
+
+      // Handle root-prefixed resolution in SSR build
+      if (cleanId.endsWith(`/${VIRTUAL_MODULE_ID}`)) {
+        return RESOLVED_VIRTUAL_ID;
+      }
+
+      return null;
+    },
+
+    /**
+     * Generate the route manifest module.
+     *
+     * The manifest exports the route tree as a serialized data structure
+     * with absolute import paths for all file references.
+     */
+    load(id: string) {
+      if (id !== RESOLVED_VIRTUAL_ID) return null;
+
+      // If routeTree hasn't been built yet (shouldn't happen), scan now
+      if (!ctx.routeTree) {
+        rescan();
+      }
+
+      return generateManifestModule(ctx.routeTree!);
+    },
+
+    /**
+     * Scan routes at build start.
+     *
+     * In dev mode, skip — configureServer runs after buildStart and will
+     * do its own scan. Avoids a redundant FS traversal on cold start.
+     */
+    buildStart() {
+      if (ctx.dev) return;
+      rescan();
+    },
+
+    /**
+     * Set up file watcher in dev mode.
+     *
+     * Watches app/ for file additions/deletions/renames that affect
+     * the route tree, regenerates the manifest, and invalidates
+     * dependent modules via HMR.
+     */
+    configureServer(devServer: ViteDevServer) {
+      // Initial scan (only scan point in dev — buildStart is skipped)
+      rescan();
+
+      // Watch the app directory
+      devServer.watcher.add(ctx.appDir);
+
+      const handleFileChange = (filePath: string) => {
+        // Only react to route-significant files in the app directory
+        if (!filePath.startsWith(ctx.appDir)) return;
+        if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
+
+        // Rescan the route tree
+        rescan();
+
+        // Invalidate the virtual module in all environments
+        invalidateManifest(devServer);
+      };
+
+      devServer.watcher.on('add', handleFileChange);
+      devServer.watcher.on('unlink', handleFileChange);
+      // Also watch renames (which are add+unlink) — handled by the above
+    },
+  };
+}
+
+/**
+ * Invalidate the virtual route manifest module across all Vite environments.
+ *
+ * When the route tree changes, any environment that has imported the manifest
+ * needs to be invalidated so the next request/transform picks up the new tree.
+ */
+function invalidateManifest(server: ViteDevServer): void {
+  for (const envName of Object.keys(server.environments)) {
+    const env = server.environments[envName];
+    if (!env?.moduleGraph) continue;
+
+    const mod = env.moduleGraph.getModuleById(RESOLVED_VIRTUAL_ID);
+    if (mod) {
+      env.moduleGraph.invalidateModule(mod);
+    }
+  }
+
+  // Trigger HMR full reload — route changes are structural
+  server.hot.send({ type: 'full-reload' });
+}
+
+/**
+ * Generate the virtual module source code for the route manifest.
+ *
+ * The output is a default-exported object containing the serialized route tree.
+ * All file references use absolute paths (required for virtual modules).
+ */
+function generateManifestModule(tree: RouteTree): string {
+  const imports: string[] = [];
+  let importIndex = 0;
+
+  /**
+   * Create a lazy import expression for a route file.
+   * Returns the import variable name.
+   */
+  function addImport(file: RouteFile): string {
+    const varName = `_route${importIndex++}`;
+    imports.push(`const ${varName} = () => import("${file.filePath}");`);
+    return varName;
+  }
+
+  /**
+   * Serialize a segment node to a JS object literal.
+   */
+  function serializeNode(node: SegmentNode, indent: string): string {
+    const nextIndent = indent + '  ';
+    const parts: string[] = [];
+
+    parts.push(`${nextIndent}segmentName: ${JSON.stringify(node.segmentName)},`);
+    parts.push(`${nextIndent}segmentType: ${JSON.stringify(node.segmentType)},`);
+    parts.push(`${nextIndent}urlPath: ${JSON.stringify(node.urlPath)},`);
+
+    if (node.paramName) {
+      parts.push(`${nextIndent}paramName: ${JSON.stringify(node.paramName)},`);
+    }
+
+    if (node.interceptionMarker) {
+      parts.push(`${nextIndent}interceptionMarker: ${JSON.stringify(node.interceptionMarker)},`);
+    }
+    if (node.interceptedSegmentName) {
+      parts.push(
+        `${nextIndent}interceptedSegmentName: ${JSON.stringify(node.interceptedSegmentName)},`
+      );
+    }
+
+    // File conventions — absolute paths as lazy imports
+    if (node.page) {
+      const v = addImport(node.page);
+      parts.push(
+        `${nextIndent}page: { load: ${v}, filePath: ${JSON.stringify(node.page.filePath)} },`
+      );
+    }
+    if (node.layout) {
+      const v = addImport(node.layout);
+      parts.push(
+        `${nextIndent}layout: { load: ${v}, filePath: ${JSON.stringify(node.layout.filePath)} },`
+      );
+    }
+    if (node.middleware) {
+      const v = addImport(node.middleware);
+      parts.push(
+        `${nextIndent}middleware: { load: ${v}, filePath: ${JSON.stringify(node.middleware.filePath)} },`
+      );
+    }
+    if (node.access) {
+      const v = addImport(node.access);
+      parts.push(
+        `${nextIndent}access: { load: ${v}, filePath: ${JSON.stringify(node.access.filePath)} },`
+      );
+    }
+    if (node.route) {
+      const v = addImport(node.route);
+      parts.push(
+        `${nextIndent}route: { load: ${v}, filePath: ${JSON.stringify(node.route.filePath)} },`
+      );
+    }
+    if (node.error) {
+      const v = addImport(node.error);
+      parts.push(
+        `${nextIndent}error: { load: ${v}, filePath: ${JSON.stringify(node.error.filePath)} },`
+      );
+    }
+    if (node.default) {
+      const v = addImport(node.default);
+      parts.push(
+        `${nextIndent}default: { load: ${v}, filePath: ${JSON.stringify(node.default.filePath)} },`
+      );
+    }
+    if (node.denied) {
+      const v = addImport(node.denied);
+      parts.push(
+        `${nextIndent}denied: { load: ${v}, filePath: ${JSON.stringify(node.denied.filePath)} },`
+      );
+    }
+    if (node.searchParams) {
+      const v = addImport(node.searchParams);
+      parts.push(
+        `${nextIndent}searchParams: { load: ${v}, filePath: ${JSON.stringify(node.searchParams.filePath)} },`
+      );
+    }
+
+    // Status-code files
+    if (node.statusFiles && node.statusFiles.size > 0) {
+      const statusEntries: string[] = [];
+      for (const [code, file] of node.statusFiles) {
+        const v = addImport(file);
+        statusEntries.push(
+          `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
+        );
+      }
+      parts.push(`${nextIndent}statusFiles: {\n${statusEntries.join(',\n')}\n${nextIndent}},`);
+    }
+
+    // JSON status-code files
+    if (node.jsonStatusFiles && node.jsonStatusFiles.size > 0) {
+      const jsonEntries: string[] = [];
+      for (const [code, file] of node.jsonStatusFiles) {
+        const v = addImport(file);
+        jsonEntries.push(
+          `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
+        );
+      }
+      parts.push(`${nextIndent}jsonStatusFiles: {\n${jsonEntries.join(',\n')}\n${nextIndent}},`);
+    }
+
+    // Legacy status files
+    if (node.legacyStatusFiles && node.legacyStatusFiles.size > 0) {
+      const legacyEntries: string[] = [];
+      for (const [name, file] of node.legacyStatusFiles) {
+        const v = addImport(file);
+        legacyEntries.push(
+          `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
+        );
+      }
+      parts.push(
+        `${nextIndent}legacyStatusFiles: {\n${legacyEntries.join(',\n')}\n${nextIndent}},`
+      );
+    }
+
+    // Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.)
+    if (node.metadataRoutes && node.metadataRoutes.size > 0) {
+      const metaEntries: string[] = [];
+      for (const [name, file] of node.metadataRoutes) {
+        const v = addImport(file);
+        metaEntries.push(
+          `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
+        );
+      }
+      parts.push(
+        `${nextIndent}metadataRoutes: {\n${metaEntries.join(',\n')}\n${nextIndent}},`
+      );
+    }
+
+    // Children
+    if (node.children.length > 0) {
+      const childNodes = node.children.map((c) => serializeNode(c, nextIndent));
+      parts.push(`${nextIndent}children: [\n${childNodes.join(',\n')}\n${nextIndent}],`);
+    } else {
+      parts.push(`${nextIndent}children: [],`);
+    }
+
+    // Parallel slots
+    if (node.slots.size > 0) {
+      const slotEntries: string[] = [];
+      for (const [slotName, slotNode] of node.slots) {
+        slotEntries.push(
+          `${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + '  ')}`
+        );
+      }
+      parts.push(`${nextIndent}slots: {\n${slotEntries.join(',\n')}\n${nextIndent}},`);
+    } else {
+      parts.push(`${nextIndent}slots: {},`);
+    }
+
+    return `${indent}{\n${parts.join('\n')}\n${indent}}`;
+  }
+
+  const rootSerialized = serializeNode(tree.root, '  ');
+
+  // Proxy file
+  let proxyLine = '';
+  if (tree.proxy) {
+    const v = addImport(tree.proxy);
+    proxyLine = `  proxy: { load: ${v}, filePath: ${JSON.stringify(tree.proxy.filePath)} },`;
+  }
+
+  // Interception rewrites — computed at build time from the route tree.
+  // Only interceptedPattern and interceptingPrefix are needed at runtime.
+  const rewrites = collectInterceptionRewrites(tree.root);
+  const rewritesLine =
+    rewrites.length > 0
+      ? `  interceptionRewrites: ${JSON.stringify(rewrites.map((r) => ({ interceptedPattern: r.interceptedPattern, interceptingPrefix: r.interceptingPrefix })))},`
+      : '';
+
+  const code = [
+    '// Auto-generated route manifest — do not edit.',
+    '// Generated by timber-routing plugin.',
+    '',
+    ...imports,
+    '',
+    'const manifest = {',
+    proxyLine,
+    rewritesLine,
+    `  root: ${rootSerialized},`,
+    '};',
+    '',
+    'export default manifest;',
+  ]
+    .filter((line) => line !== undefined && line !== '')
+    .join('\n');
+
+  return code;
+}