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

package/docs/more/03-coming-from-nextjs.mdx

@@ -0,0 +1,186 @@
+---
+title: 'Coming from Next.js'
+description: 'A practical mapping for Next.js developers — in Next.js you did X, in timber you do Y.'
+slug: 'coming-from-nextjs'
+---
+
+# Coming from Next.js
+
+This page maps Next.js patterns to timber equivalents. It's not a comparison (see [timber vs Next.js](/docs/timber-vs-nextjs) for that) — it's a migration mental model.
+
+## Data Fetching
+
+**Next.js:** `getServerSideProps`, `getStaticProps`, or `fetch()` with implicit caching.
+
+**timber:** Async server components. No loaders, no special functions. `fetch()` is never patched or cached — use `timber.cache()` explicitly when you want caching.
+
+```tsx title="app/products/page.tsx"
+// timber — just an async component
+export default async function ProductsPage() {
+  const products = await db.products.findMany();
+  return <ProductList products={products} />;
+}
+```
+
+## `loading.tsx`
+
+**Next.js:** `loading.tsx` convention inserts a Suspense boundary automatically.
+
+**timber:** No `loading.tsx`. Place `<Suspense>` explicitly where you want it. This keeps you in control of what streams and what blocks the HTTP status code.
+
+```tsx
+// timber — explicit Suspense
+import { Suspense } from 'react';
+
+export default async function Page() {
+  const product = await getProduct(id); // blocks, can affect status code
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <Suspense fallback={<Skeleton />}>
+        <Reviews productId={id} /> {/* streams in */}
+      </Suspense>
+    </div>
+  );
+}
+```
+
+## Middleware
+
+**Next.js:** Single global `middleware.ts` at the project root. Matcher patterns select routes.
+
+**timber:** Per-segment `middleware.ts` files. Place them at the route level that matches the concern. `proxy.ts` for global concerns (CORS, rate limiting, security headers).
+
+```
+app/
+  proxy.ts                    # Global — every request (like Next.js middleware but with next())
+  dashboard/
+    middleware.ts             # Only runs for /dashboard/*
+    settings/
+      middleware.ts           # Only runs for /dashboard/settings/*
+```
+
+## `useSearchParams`
+
+**Next.js:** `useSearchParams()` hook returns a `URLSearchParams` object.
+
+**timber:** Typed search params via `defineSearchParams` in a `params.ts` file. Server reads via `.get()`, client reads/writes via `.useQueryStates()`. Segment params are defined globally in `app/schema.ts` via `defineSchema()`, accessed with `getSegmentParams(SEGMENT_PATH)` using the `$segment` module.
+
+```ts title="app/products/params.ts"
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: z.coerce.number().default(1),
+  sort: z.enum(['price', 'name']).default('name'),
+});
+```
+
+## Caching
+
+**Next.js:** Implicit fetch caching, `unstable_cache`, ISR with `revalidate`.
+
+**timber:** No implicit caching. No ISR. Explicit `cache.data()` with TTL and tags:
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+declare const db: { products: { findPopular(): Promise<{ id: string; name: string }[]> } };
+
+const getProducts = cache.data(
+  async () => db.products.findPopular(),
+  { ttl: 300, tags: ['products'] }
+);
+```
+
+## Authorization
+
+**Next.js:** Usually done in middleware or layout components. No built-in access gate pattern.
+
+**timber:** `access.ts` per segment. Runs inside the React tree with `React.cache` sharing. Supports slot degradation (a denied slot renders `denied.tsx` instead of failing the whole page).
+
+```ts title="app/(auth)/access.ts"
+import { redirect, getCookieJar } from '@timber-js/app/server';
+
+declare function getSessionFromCookie(jar: ReturnType<typeof getCookieJar>): { userId: string } | null;
+
+export default async function access() {
+  const session = getSessionFromCookie(getCookieJar());
+  if (!session) redirect('/login');
+}
+```
+
+## Server Actions
+
+**Next.js:** Server actions with `'use server'`. `useFormState` / `useFormStatus`.
+
+**timber:** `createActionClient` for reusable middleware (auth, validation). `useActionState` from `@timber-js/app/client` returns a 4-tuple with auto-derived errors. Forms work without JavaScript via form flash.
+
+```ts title="lib/action.ts"
+import { createActionClient, ActionError } from '@timber-js/app/server';
+import { getUser } from '@/lib/auth';
+
+export const action = createActionClient({
+  middleware: async () => {
+    const user = await getUser();
+    if (!user) throw new ActionError('UNAUTHORIZED');
+    return { user };
+  },
+});
+```
+
+## `notFound()`
+
+**Next.js:** `notFound()` function.
+
+**timber:** `deny(404)` — sends a real HTTP 404 status code:
+
+```tsx
+import { deny } from '@timber-js/app/server';
+
+if (!product) deny(404);
+```
+
+## `redirect()`
+
+**Next.js:** `redirect()` from `next/navigation`.
+
+**timber:** `redirect()` from `@timber-js/app/server`. Same concept, different import:
+
+```ts
+import { redirect } from '@timber-js/app/server';
+
+redirect('/login');        // 302 by default
+redirect('/login', 301);   // Permanent redirect
+```
+
+Code that imports `redirect()` or `notFound()` from `next/navigation` works unmodified — including calls during client component render, which timber converts into an SPA navigation (`redirect`) or your nearest 404 boundary (`notFound`), matching Next.js behavior.
+
+## Metadata
+
+**Next.js:** `export const metadata` or `export async function generateMetadata()`.
+
+**timber:** Same pattern — export `metadata` (static) or a `metadata()` function (dynamic) from any page or layout.
+
+## Imports
+
+| Next.js import            | timber import                              |
+| ------------------------- | ------------------------------------------ |
+| `next/link`               | `@timber-js/app/client` (`Link`)           |
+| `next/navigation`         | `@timber-js/app/client` (`useRouter`, etc) |
+| `next/headers`            | `@timber-js/app/server` (`getHeaders`)     |
+| `next/server`             | `@timber-js/app/server`                    |
+| `unstable_cache`          | `@timber-js/app/cache` (`cache`)           |
+
+## Key Differences Summary
+
+| Concept              | Next.js                          | timber                                |
+| -------------------- | -------------------------------- | ------------------------------------- |
+| Fetch caching        | Implicit, patched `fetch`        | Explicit `timber.cache()`             |
+| ISR                  | Built-in                         | Not supported (use cache + TTL)       |
+| `loading.tsx`        | Convention                       | Use explicit `<Suspense>`             |
+| Middleware            | Single global file              | Per-segment + global `proxy.ts`       |
+| Status codes         | Often 200 for errors            | Real HTTP status codes always         |
+| Auth                 | In middleware or components      | `access.ts` with slot degradation     |
+| Search params        | Untyped `URLSearchParams`       | Typed codecs with validation          |
+| Forms without JS     | Limited support                 | Full form flash support               |

package/docs/more/04-metadata-and-fonts.mdx

@@ -0,0 +1,193 @@
+---
+title: 'Metadata and Fonts'
+description: 'Page titles, Open Graph, metadata routes, Google Fonts, and local fonts.'
+slug: 'metadata-and-fonts'
+---
+
+# Metadata and Fonts
+
+## Metadata
+
+Export `metadata` from any page or layout to control `<head>` tags.
+
+### Static Metadata
+
+```tsx title="app/page.tsx"
+import type { Metadata } from '@timber-js/app/server';
+
+export const metadata: Metadata = {
+  title: 'Dashboard',
+  description: 'Your project dashboard',
+};
+```
+
+### Dynamic Metadata
+
+Export `metadata` as an async function to compute values at request time:
+
+```tsx title="app/products/[id]/page.tsx"
+import type { Metadata } from '@timber-js/app/server';
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+declare function getProduct(id: string): Promise<{ name: string; summary: string; imageUrl: string }>;
+
+export async function metadata(): Promise<Metadata> {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+  return {
+    title: product.name,
+    description: product.summary,
+    openGraph: { images: [product.imageUrl] },
+  };
+}
+```
+
+Dynamic `metadata` runs during the render pass — `React.cache` is active, so data fetched here and in the page component is deduplicated.
+
+### Title Templates
+
+Layouts can define a title template. Pages fill in the `%s` placeholder:
+
+```tsx title="app/layout.tsx"
+export const metadata: Metadata = {
+  title: { template: '%s | My App', default: 'My App' },
+};
+```
+
+### Open Graph & Twitter Cards
+
+```tsx
+export const metadata: Metadata = {
+  openGraph: {
+    title: 'My Product',
+    description: 'The best product ever.',
+    images: [{ url: '/og-image.png', width: 1200, height: 630 }],
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: 'My Product',
+    images: ['/og-image.png'],
+  },
+};
+```
+
+### Metadata Routes
+
+Special files in your route tree generate metadata endpoints:
+
+| File                  | Output                    |
+| --------------------- | ------------------------- |
+| `sitemap.ts`          | `/sitemap.xml`            |
+| `robots.ts`           | `/robots.txt`             |
+| `manifest.ts`         | `/manifest.json`          |
+| `opengraph-image.tsx` | `/opengraph-image.png` + auto `og:image` and `twitter:image` meta tags |
+| `favicon.ico` / `favicon.tsx` | `/favicon.ico`    |
+| `icon.tsx`            | `/icon.png` + auto `<link rel="icon">` |
+
+When `opengraph-image.tsx` exists in a segment, timber automatically emits both `<meta property="og:image">` and `<meta name="twitter:image">` in `<head>` — no need to declare them in your `metadata` export. The auto-linked URL includes a cache-busting hash so social platforms pick up changes on redeploy.
+
+If you declare `openGraph.images` in your metadata, both auto-linked tags are suppressed. If you declare only `twitter.images`, the auto-linked `twitter:image` is suppressed but `og:image` is still emitted. User-declared metadata always wins.
+
+`favicon.tsx` lets you generate favicons dynamically (e.g. tenant branding). The URL stays `/favicon.ico` for browser compatibility.
+
+For OG image generation, use `@takumi-rs/image-response` (BYO package — not bundled with timber):
+
+```tsx title="app/opengraph-image.tsx"
+import { ImageResponse } from 'takumi-js/response';
+
+export default async function OpenGraphImage() {
+  return new ImageResponse(
+    <div style={{ fontSize: 48, background: 'white', width: '100%', height: '100%',
+      display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+      My App
+    </div>,
+    { width: 1200, height: 630 }
+  );
+}
+```
+
+Metadata is always complete before the flush — no client-side injection, no partial `<head>`.
+
+---
+
+## Fonts
+
+timber.js downloads, subsets, and self-hosts fonts at build time. No requests to Google at runtime. No layout shift.
+
+### Google Fonts
+
+```tsx title="app/layout.tsx"
+import { Inter, JetBrains_Mono } from '@timber-js/app/fonts/google';
+
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-sans',
+});
+
+const jetbrainsMono = JetBrains_Mono({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-mono',
+});
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${jetbrainsMono.variable}`}>
+      <body className={inter.className}>{children}</body>
+    </html>
+  );
+}
+```
+
+### Local Fonts
+
+```tsx
+import localFont from '@timber-js/app/fonts/local';
+
+const myFont = localFont({
+  src: [
+    { path: './fonts/MyFont-Regular.woff2', weight: '400' },
+    { path: './fonts/MyFont-Bold.woff2', weight: '700' },
+  ],
+  display: 'swap',
+  variable: '--font-custom',
+});
+```
+
+### Static Analysis Constraints
+
+Font calls look like runtime functions but are a build-time transform, so they must be statically analyzable. The canonical shape is a module-scope `const` (or `export const`) with a literal config object:
+
+```tsx
+const inter = Inter({ subsets: ['latin'] });        // ✅
+export const mono = JetBrains_Mono({ subsets: ['latin'] }); // ✅
+```
+
+Anything else fails the build with a descriptive error instead of silently breaking at runtime:
+
+```tsx
+export default Inter({ subsets: ['latin'] });       // ❌ build error
+const theme = { font: Inter({ subsets: ['latin'] }) }; // ❌ build error
+const cls = Inter({ subsets: ['latin'] }).className;   // ❌ build error
+import * as fonts from 'next/font/google';          // ❌ build error
+```
+
+### CSS Variables
+
+Use the `variable` option and reference it in your styles:
+
+```css title="globals.css"
+body { font-family: var(--font-sans), system-ui, sans-serif; }
+code { font-family: var(--font-mono); }
+```
+
+### Next.js Compatibility
+
+Imports from `next/font/google` and `next/font/local` are shimmed — existing code works without changes:
+
+```tsx
+import { Inter } from 'next/font/google';
+import localFont from 'next/font/local';
+```

package/docs/more/04b-mdx.mdx

@@ -0,0 +1,209 @@
+---
+title: 'MDX'
+description: 'Use MDX to write pages in Markdown with embedded React components — server-rendered by default, zero client JS.'
+---
+
+# MDX
+
+MDX lets you write pages in Markdown with embedded React components. In timber.js, MDX pages are **server components by default** — they render on the server with zero client JavaScript unless a component explicitly opts in with `'use client'`.
+
+## Setup
+
+Add `'mdx'` to `pageExtensions` in your config:
+
+```ts title="timber.config.ts"
+export default {
+  pageExtensions: ['tsx', 'ts', 'jsx', 'js', 'mdx'],
+};
+```
+
+Install the MDX compiler and frontmatter plugins:
+
+```bash title="Terminal"
+pnpm add -D @mdx-js/rollup remark-frontmatter remark-mdx-frontmatter
+```
+
+That's it. Any `page.mdx` file in your `app/` directory is now a route.
+
+## Page-Level MDX
+
+A `page.mdx` works exactly like `page.tsx` — it becomes a route based on its directory:
+
+```
+app/
+  docs/
+    getting-started/
+      page.mdx          # /docs/getting-started
+    api-reference/
+      page.mdx          # /docs/api-reference
+    layout.tsx           # shared docs layout
+```
+
+MDX pages support `export const metadata` for page titles and descriptions:
+
+````mdx title="app/docs/getting-started/page.mdx"
+export const metadata = { title: 'Getting Started' }
+
+# Getting Started
+
+Install timber.js:
+
+```bash
+pnpm add @timber-js/app
+```
+
+This page is a **server component** — no JavaScript shipped to the browser.
+````
+
+## Frontmatter
+
+timber.js automatically registers `remark-frontmatter` and `remark-mdx-frontmatter` when installed. Frontmatter is exported as a single `frontmatter` object:
+
+````mdx title="app/blog/hello/page.mdx"
+---
+title: Hello World
+description: My first post
+---
+
+# {frontmatter.title}
+
+{frontmatter.description}
+````
+
+You can import the frontmatter object from another MDX file:
+
+```tsx title="app/blog/layout.tsx"
+import { frontmatter } from './page.mdx';
+
+// frontmatter.title, frontmatter.description, etc.
+```
+
+For page metadata, use an explicit `export const metadata` — frontmatter alone does not set metadata automatically:
+
+````mdx title="app/docs/getting-started/page.mdx"
+---
+title: Getting Started
+---
+
+export const metadata = { title: 'Getting Started' }
+
+# {frontmatter.title}
+````
+
+## Custom Components
+
+Create `mdx-components.tsx` at the project root to customize how Markdown elements render:
+
+```tsx title="mdx-components.tsx"
+import type { MDXComponents } from 'mdx/types';
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+  return {
+    ...components,
+    h1: (props) => <h1 className="text-3xl font-bold mt-8 mb-4" {...props} />,
+    pre: (props) => <pre className="bg-gray-900 text-gray-100 p-4 rounded-lg" {...props} />,
+    code: (props) => <code className="bg-gray-100 px-1.5 py-0.5 rounded text-sm" {...props} />,
+  };
+}
+```
+
+timber.js detects this file at startup and applies it to all MDX files automatically. The file can also live in `src/`.
+
+## Using Client Components in MDX
+
+MDX files stay on the server. To add interactivity, import a `'use client'` component:
+
+````mdx title="app/docs/getting-started/page.mdx"
+import { CopyButton } from '../../components/copy-button'
+
+# Getting Started
+
+```bash
+pnpm add @timber-js/app
+```
+
+<CopyButton text="pnpm add @timber-js/app" />
+````
+
+Only the `CopyButton` ships JavaScript. The rest of the page renders as static HTML.
+
+## Remark and Rehype Plugins
+
+Configure remark and rehype plugins through the `mdx` key in your config:
+
+```ts title="timber.config.ts"
+import remarkGfm from 'remark-gfm';
+import rehypeShiki from '@shikijs/rehype';
+
+export default {
+  pageExtensions: ['tsx', 'ts', 'jsx', 'js', 'mdx'],
+  mdx: {
+    remarkPlugins: [remarkGfm],
+    rehypePlugins: [[rehypeShiki, { theme: 'monokai' }]],
+  },
+};
+```
+
+The `mdx` config maps directly to `@mdx-js/rollup` options. Available fields:
+
+| Option                | Type            | Description                                |
+| --------------------- | --------------- | ------------------------------------------ |
+| `remarkPlugins`       | `PluggableList` | remark plugins for Markdown AST transforms |
+| `rehypePlugins`       | `PluggableList` | rehype plugins for HTML AST transforms     |
+| `recmaPlugins`        | `PluggableList` | recma plugins for ESTree transforms        |
+| `remarkRehypeOptions` | `object`        | Options passed to `remark-rehype`          |
+
+Plugins like `remark-gfm` and `rehype-shiki` are your choice to install — timber.js doesn't bundle them.
+
+## Dynamic MDX Loading
+
+For content-driven pages like a blog, use `import.meta.glob()` to build a map of MDX modules, then load the right one based on the URL:
+
+```tsx title="app/blog/[slug]/page.tsx"
+import { allBlogs } from 'content-collections';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+import { SEGMENT_PATH } from './$segment';
+
+const mdxModules = import.meta.glob<{ default: React.ComponentType }>(
+  '../../../content/blog/*.mdx'
+);
+
+export default async function BlogPost() {
+  const { slug } = getSegmentParams(SEGMENT_PATH);
+  const post = allBlogs.find((p) => p.slug === slug);
+  if (!post) deny(404);
+
+  const key = `../../../content/blog/${post._meta.fileName}`;
+  const loader = mdxModules[key];
+  if (!loader) deny(404);
+
+  const { default: MdxComponent } = await loader();
+
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <MdxComponent />
+    </article>
+  );
+}
+```
+
+`import.meta.glob()` is resolved at build time by Vite — each `.mdx` file becomes a real ES module in the bundle with no `eval` or `new Function()` at runtime. The glob path is relative to the file that calls it.
+
+This pattern pairs with [content collections](/docs/content-collections) — the collection provides typed metadata (title, date, tags), while `import.meta.glob()` loads the MDX body as a React component.
+
+An alternative is `compileMDX()` from `@content-collections/mdx`, which compiles MDX to a serialized string during the content collection transform step. You then render it at runtime with `useMDXComponent(code)`. This avoids glob paths but trades them for a runtime eval of the compiled output. `import.meta.glob()` keeps everything as real ES modules resolved at build time.
+
+## Content Collections
+
+For structured content outside the route tree (blog posts, docs, changelogs), use [content collections](/docs/content-collections). Collections give you typed schemas, slug generation, and build-time validation — while MDX page routes are for pages that live directly in `app/`.
+
+## Coming from Next.js
+
+| Next.js                                   | timber.js                                     |
+| ----------------------------------------- | --------------------------------------------- |
+| `@next/mdx` wrapper package               | Built-in — just add `'mdx'` to pageExtensions |
+| `next.config.mjs` `withMDX()` wrapper     | `timber.config.ts` `mdx` key                  |
+| MDX pages are client components by default | MDX pages are server components by default     |
+| Custom loader for `.md` files              | `@mdx-js/rollup` handles both `.mdx` and `.md` |
+| `mdx-components.tsx` at project root       | Same convention                               |

package/docs/more/05-content-collections.mdx

@@ -0,0 +1,90 @@
+---
+title: 'Content Collections'
+description: 'Typed file-based content with Zod schemas, MDX rendering, and virtual module access.'
+---
+
+# Content Collections
+
+Content collections let you define typed, file-based content in a `content/` directory. Each collection has a Zod schema for frontmatter validation and a transform for processing (like MDX compilation).
+
+## Defining a Collection
+
+```ts
+// content-collections.ts
+import { defineCollection, defineConfig } from '@content-collections/core';
+import { compileMDX } from '@content-collections/mdx';
+import { z } from 'zod/v4';
+
+const docs = defineCollection({
+  name: 'docs',
+  directory: 'content/docs',
+  include: '**/*.{mdx,md}',
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    order: z.number(),
+    section: z.string().optional(),
+  }),
+  transform: async (document, context) => {
+    const mdx = await compileMDX(context, document);
+    return { ...document, mdx };
+  },
+});
+
+export default defineConfig({ collections: [docs] });
+```
+
+## Using Collections
+
+Import the generated collection and query it:
+
+```tsx
+import { allDocs } from 'content-collections';
+import { getSegmentParams, deny } from '@timber-js/app/server';
+
+declare const allDocs: { title: string; _meta: { fileName: string }; mdx: { default: React.ComponentType } }[];
+
+export default async function DocsPage() {
+  const { slug } = getSegmentParams();
+  const doc = allDocs.find((d) => d._meta.fileName === slug);
+  if (!doc) deny(404);
+
+  return (
+    <article className="prose">
+      <h1>{doc.title}</h1>
+      <doc.mdx.default />
+    </article>
+  );
+}
+```
+
+## Content Directory Structure
+
+```tsx
+content / docs / v1 / getting - started.mdx;
+routing.mdx;
+blog / hello - world.mdx;
+```
+
+Each file's `_meta` includes `path`, `fileName`, and `directory` — useful for filtering by version, building sidebar navigation, or generating static params.
+
+## MDX Components
+
+Customize MDX rendering with `mdx-components.tsx`:
+
+```tsx
+// mdx-components.tsx
+import type { MDXComponents } from 'mdx/types';
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+  return {
+    ...components,
+    h1: ({ children }) => <h1 className="text-3xl font-bold">{children}</h1>,
+    code: ({ children }) => <code className="bg-gray-100 rounded px-1">{children}</code>,
+  };
+}
+```
+
+## Type Generation
+
+Content collections generate TypeScript types at build time. Every document is fully typed — frontmatter fields, computed properties from transforms, and `_meta` information.