@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

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

@@ -1,186 +0,0 @@
----
-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 any module you import. 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/search-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

@@ -1,193 +0,0 @@
----
-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-js/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

@@ -1,229 +0,0 @@
----
-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 — timber.js uses [Satteri](https://satteri.bruits.org), a Rust-based Markdown/MDX compiler with a native Vite plugin:
-
-```bash title="Terminal"
-pnpm add -D vite-plugin-satteri satteri
-```
-
-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
-
-Frontmatter parsing is built in — YAML between `---` fences or TOML between `+++` fences. 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.
-
-## Plugins and Features
-
-GFM (tables, footnotes, strikethrough, task lists) and frontmatter are on by default. Additional syntax is enabled through `features`, and custom transforms are written as Satteri visitor plugins through the `mdx` key in your config:
-
-```ts title="timber.config.ts"
-import { defineHastPlugin } from 'satteri';
-
-const externalLinks = defineHastPlugin({
-  name: 'external-links',
-  element: {
-    filter: ['a'],
-    visit(node, ctx) {
-      const href = node.properties.href;
-      if (typeof href === 'string' && href.startsWith('http')) {
-        ctx.setProperty(node, 'target', '_blank');
-      }
-    },
-  },
-});
-
-export default {
-  pageExtensions: ['tsx', 'ts', 'jsx', 'js', 'mdx'],
-  mdx: {
-    hastPlugins: [externalLinks],
-    features: { math: true },
-  },
-};
-```
-
-The `mdx` config maps directly to `vite-plugin-satteri` options. Available fields:
-
-| Option         | Type                 | Description                                                                     |
-| -------------- | -------------------- | ------------------------------------------------------------------------------- |
-| `mdastPlugins` | `MdastPluginInput[]` | Markdown AST visitors (created with `defineMdastPlugin`)                        |
-| `hastPlugins`  | `HastPluginInput[]`  | HTML AST visitors (created with `defineHastPlugin`)                             |
-| `features`     | `Features`           | Parser toggles — `gfm`, `frontmatter`, `math`, `directive`, `wikilinks`, …      |
-
-Satteri plugins are filtered visitors, not unified plugins — **remark/rehype plugins do not run** on Satteri's Rust-side AST. Visitors can be async and can replace nodes, which is enough to build things like shiki-based syntax highlighting (shiki transformers such as `@shikijs/twoslash` still work, since they run inside shiki).
-
-If you need the unified MDX pipeline (for example, CodeHike), bypass timber's MDX support entirely: set `mdx: false` in your config and register `@mdx-js/rollup` yourself in `vite.config.ts` with `enforce: 'pre'`:
-
-```ts title="timber.config.ts"
-export default {
-  mdx: false, // disable timber's built-in MDX — bring your own compiler
-};
-```
-
-## 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     |
-| unified (remark/rehype) plugins            | Satteri visitor plugins + built-in features   |
-| Custom loader for `.md` files              | Built in — `.md` imports export an HTML string |
-| `mdx-components.tsx` at project root       | Same convention                               |

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

@@ -1,90 +0,0 @@
----
-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.