@timber-js/app 0.2.0-alpha.195 → 0.2.0-alpha.197

package/docs/learn/04b-the-flush-point.mdx

@@ -1,115 +0,0 @@
----
-title: 'The Flush Point'
-description: 'When timber commits the HTTP status code and why it matters.'
-slug: 'the-flush-point'
-# notAI: true
----
-
-# The Flush Point
-
-The flush point is when the framework sends the first byte of HTML to the browser and commits the HTTP status code. In a traditional PHP website, this happens all at once.
-
-But modern web frameworks, and notably react server components, have embraced a streaming architecture. Allowing you to send content _after_ the flush point.
-
-While this is ultimately incredibly powerful, it brings forth confusion because contextually, code can have different side effects depending on _when_ you call it.
-
-On a next.js app, if I call `notFound()` inside of a `page.tsx` that has a sibling `loading.tsx` – my status code will return `200`. By obfuscating the flush point, we've actually just made developer clarity murky.
-
-So timber works differently. At no point does timber flush early, unless _you_ (the developer), choose to place a `<Suspense>` boundary. Often this will end up being below your `page.tsx` level, so you'll still have access to controlling and sending proper status codes.
-
-------
-
-AI below..
-
-## The Problem
-
-Most streaming frameworks send a `200 OK` immediately and figure out the real outcome later:
-
-```
-Request → 200 OK → ... render ... → oh, it's a 404
-```
-
-By the time the server discovers the page doesn't exist, the status code is already sent. The client sees `200`. Search engines see `200`. CDNs cache it as `200`.
-
-This breaks search engines (deleted pages never deindex), CDNs (404s get cached as successes), monitoring (zero errors while users see broken pages), and `curl`/scripts (`curl -f` won't detect the failure).
-
-## timber's Solution
-
-timber holds the response until it knows the real outcome:
-
-```
-Request arrives
-  → Route matched
-  → proxy.ts runs
-  → middleware.ts runs
-  → access.ts runs
-  → React shell renders (onShellReady)
-  → ✓ Status code committed ← flush point
-  → Shell HTML sent to browser
-  → Suspense boundaries stream in
-```
-
-The status code commits when **all three** conditions are met:
-
-1. Middleware completed without returning a response
-2. All access checks passed (or denied with a real status code)
-3. React's `onShellReady` fired — the synchronous shell rendered without error
-
-A missing page returns a real `404`. A failed auth check returns a real `403`. A redirect returns a real `302`. The HTTP layer tells the truth.
-
-## Before and After the Flush
-
-**Before the flush** (blocking):
-
-- `proxy.ts` — global request processing
-- `middleware.ts` — route-level request processing
-- `access.ts` — authorization gates
-- Synchronous component rendering (the shell)
-
-**After the flush** (streaming):
-
-- `<Suspense>` boundaries resolve and stream in
-- Slow data loads complete
-- The page progressively fills in
-
-``` leading="none"
-         ┌─────── flush point
-         │
-         ▼
-├────────┤──────────────────────────┤
- blocking    streaming
- (shell)     (suspense boundaries)
-```
-
-Everything before the flush determines the status code. Everything after streams progressively. You control the boundary by choosing what goes inside `<Suspense>` and what doesn't.
-
-## Pages Work Without JavaScript
-
-Because timber holds the flush until the shell is complete, the browser receives a fully-formed HTML document. Content is visible, links work as standard `<a>` tags, and forms submit as standard POSTs. JavaScript adds client-side navigation, interactive components, and streaming updates — but the page works without it.
-
-This isn't a special mode. It's how timber works by default.
-
-## Early Hints
-
-timber doesn't make you wait for assets while the shell renders. At route-match time — before middleware runs — timber sends `103 Early Hints` with CSS, JS, and font URLs. The browser starts downloading assets while the server is still working:
-
-```
-103 Early Hints
-Link: </styles/main.css>; rel=preload; as=style
-Link: </chunks/page-abc.js>; rel=modulepreload
-
-... middleware runs, shell renders ...
-
-200 OK
-<html>...
-```
-
-You get the correctness of a held flush with the performance of early resource loading.
-
-## How to Think About It
-
-Primary content — the data that defines whether a page exists, who can see it, and what it contains — should load before the flush. Put it in your components directly.
-
-Secondary content — recommendations, activity feeds, analytics widgets — can load after the flush. Wrap it in `<Suspense>`.
-
-The flush point is the dividing line between "what the page _is_" and "what the page _also shows_."

package/docs/learn/12-client-navigation.mdx

@@ -1,176 +0,0 @@
----
-title: 'Client Navigation'
-description: 'The Link component, useRouter, segment cache, and scroll restoration.'
-slug: 'client-navigation'
----
-
-# Client Navigation
-
-timber.js supports client-side navigation via the `<Link>` component. Clicking a link fetches an RSC payload from the server and reconciles the DOM without a full page reload.
-
-## `<Link>`
-
-```tsx
-import { Link } from '@timber-js/app/client';
-
-<Link href="/about">About</Link>
-<Link href="/products/123">Product</Link>
-<Link href="/dashboard" replace>Dashboard</Link>
-```
-
-`<Link>` type-checks `href` against the generated route map. Invalid routes produce a TypeScript error.
-
-## `useRouter`
-
-For programmatic navigation:
-
-```tsx title="app/components/logout-button.tsx"
-'use client';
-
-import { useRouter } from '@timber-js/app/client';
-
-declare function logout(): Promise<void>;
-
-export function LogoutButton() {
-  const router = useRouter();
-
-  async function handleLogout() {
-    await logout();
-    router.push('/login');
-  }
-
-  return <button onClick={handleLogout}>Log out</button>;
-}
-```
-
-| Method                 | Description                              |
-| ---------------------- | ---------------------------------------- |
-| `router.push(href)`   | Navigate to a new URL                    |
-| `router.replace(href)` | Navigate without adding a history entry |
-| `router.refresh()`    | Re-fetch the current route's RSC payload |
-| `router.back()`       | Go back in history                       |
-| `router.forward()`    | Go forward in history                    |
-
-## `usePathname`
-
-Returns the current pathname:
-
-```tsx
-'use client';
-import { usePathname, Link } from '@timber-js/app/client';
-
-export function NavLink({ href, children }: { href: string; children: React.ReactNode }) {
-  const pathname = usePathname();
-  const isActive = pathname === href;
-  return (
-    <Link href={href} className={isActive ? 'font-bold' : ''}>
-      {children}
-    </Link>
-  );
-}
-```
-
-## `useSelectedLayoutSegment`
-
-Returns the active segment within a layout — useful for highlighting nav items:
-
-```tsx
-'use client';
-import { useSelectedLayoutSegment } from '@timber-js/app/client';
-
-export function DashboardNav() {
-  const segment = useSelectedLayoutSegment();
-  // segment is "settings", "projects", etc.
-}
-```
-
-## `useLinkStatus`
-
-Track per-link pending state during navigation:
-
-```tsx
-'use client';
-import { Link, useLinkStatus } from '@timber-js/app/client';
-
-function NavItemInner({ children }: { children: React.ReactNode }) {
-  const { isPending } = useLinkStatus();
-  return <span className={isPending ? 'opacity-50' : ''}>{children}</span>;
-}
-
-export function NavItem({ href, children }: { href: string; children: React.ReactNode }) {
-  return (
-    <Link href={href}>
-      <NavItemInner>{children}</NavItemInner>
-    </Link>
-  );
-}
-```
-
-## Segment Cache
-
-Opt-in via `clientSegmentCache: true` in `timber.config.ts`. When enabled, the client maintains a mirror of the server's segment tree. On navigation, only changed segments are re-fetched:
-
-```ts title="timber.config.ts"
-export default {
-  clientSegmentCache: true,
-};
-```
-
-```
-/dashboard/settings → /dashboard/team
-
-  Root Layout       ← sync, mounted → skip
-  Auth Layout       ← sync, mounted → skip
-  Dashboard Layout  ← sync, mounted → skip
-  Team Page         ← new            → fetch from server
-```
-
-Sync layouts stay cached while mounted. Async layouts always re-render. Pages always re-render. Client component state in shared layouts is preserved — counters, form inputs, scroll positions survive navigation.
-
-When disabled (the default), every client navigation gets a full RSC payload from the server. This is simpler and avoids edge cases with stale cached layouts, at the cost of slightly larger payloads on navigation.
-
-Back/forward navigation replays cached RSC payloads instantly — no server roundtrip.
-
-## Scroll Restoration
-
-- **Forward navigation** scrolls to the top of the page.
-- **Back/forward** restores the saved scroll position.
-- **Hash fragments** — `<Link href="/docs/api#install">` commits the full URL (including the `#fragment`) to the address bar and scrolls to the matching element after render, just like a plain `<a>` without JavaScript. If no element matches, navigation falls back to scroll-to-top.
-
-Pass `scroll={false}` to `<Link>` or `router.push` to preserve the current scroll position:
-
-```tsx
-<Link href="/dashboard/settings" scroll={false}>Settings</Link>
-```
-
-```tsx
-router.push('/dashboard/settings', { scroll: false });
-```
-
-### Custom Scroll Containers
-
-If your layout uses a custom scrollable container, add `data-timber-scroll-restoration`:
-
-```tsx
-<main className="overflow-y-auto h-screen" data-timber-scroll-restoration>
-  {children}
-</main>
-```
-
-## `Link.onNavigate`
-
-Intercept navigation for view transitions:
-
-```tsx
-<Link
-  href="/gallery"
-  onNavigate={(e) => {
-    if (document.startViewTransition) {
-      e.preventDefault();
-      document.startViewTransition(() => e.navigate());
-    }
-  }}
->
-  Gallery
-</Link>
-```

package/docs/learn/13-configuration.mdx

@@ -1,166 +0,0 @@
----
-title: 'Configuration'
-description: 'timber.config.ts — output mode, adapters, caching, and the two-phase model.'
-slug: 'configuration'
----
-
-# Configuration
-
-timber.js is configured through `timber.config.ts` at the project root. Vite configuration lives separately in `vite.config.ts`.
-
-## Minimal Config
-
-```ts title="timber.config.ts"
-export default {
-  output: 'server',
-};
-```
-
-That's it for most projects. The defaults are sensible.
-
-## How the Config Is Loaded
-
-`timber.config.ts` is loaded by Node.js itself using built-in type stripping — it is not bundled by Vite. This requires Node.js 22.18 or newer, and the file must stick to erasable TypeScript syntax: type annotations, interfaces, and `satisfies` are fine, but enums, namespaces, and constructor parameter properties will fail to load. Your `package.json` should declare `"type": "module"` (the default for new timber projects) so the `export default` syntax parses correctly.
-
-If the config file fails to load for any reason, every command — `timber dev`, `timber build`, and `timber preview` — stops with an error naming the file. A broken config never silently falls back to defaults.
-
-## Output Modes
-
-| Mode                                   | Server required | Client JS                 | Server Actions |
-| -------------------------------------- | --------------- | ------------------------- | -------------- |
-| `'server'`                             | Yes             | Yes                       | Yes            |
-| `'static'`                             | No              | Yes (hydration + SPA nav) | Via adapter    |
-| `'static'` + `clientJavascript: false` | No              | None                      | Build error    |
-
-```ts title="timber.config.ts"
-// Static site with no JavaScript
-export default {
-  output: 'static',
-  clientJavascript: false,
-};
-```
-
-## Build Time vs Request Time
-
-The `output` field shifts work between two phases:
-
-**Build time** happens once when you run `timber build`. There's no request, no user, no cookies. Route scanning, client boundary discovery, server action extraction, font downloading, and asset bundling all happen here.
-
-**Request time** happens per incoming HTTP request. Middleware, access checks, server components, caching, cookies, and server actions all run here.
-
-| `output`   | `middleware.ts`       | Server components              | Server actions                              |
-| ---------- | --------------------- | ------------------------------ | ------------------------------------------- |
-| `'server'` | Request time          | Request time                   | Request time                                |
-| `'static'` | **Build time only**   | **Build time** (once, to HTML) | **Request time**, split-deployed as endpoints |
-
-This is why `cookies()` and `headers()` are build errors in static mode — there's no request at the moment components render.
-
-Dynamic routes (`[param]`) must export `generateStaticSegmentParams` when using `output: 'static'` — the build needs to know which URLs to render. API routes (`route.ts`) are also pre-rendered at build time.
-
-For each page, the build generates both HTML (for initial loads) and RSC flight data (for client-side SPA navigation). No server is needed at runtime.
-
-## Adapters
-
-Adapters transform the build output for your deployment platform:
-
-```ts title="timber.config.ts"
-import { cloudflare } from '@timber-js/app/adapters/cloudflare';
-
-export default {
-  output: 'server',
-  adapter: cloudflare(),
-};
-```
-
-```ts title="timber.config.ts"
-import { nitro } from '@timber-js/app/adapters/nitro';
-
-export default {
-  output: 'server',
-  adapter: nitro({ preset: 'node-server' }),
-};
-```
-
-`cloudflare()` for Cloudflare Workers. `nitro({ preset })` for everything else — Node.js, Vercel, Netlify, AWS Lambda, Deno, Bun, Azure.
-
-## Cache Handler
-
-Cache handler configuration lives in a separate `timber.cache.ts` file (not `timber.config.ts`). This keeps runtime cache instances separate from build-time config, preventing build dependencies from leaking into the server bundle.
-
-```ts title="timber.cache.ts"
-import { MemoryCacheHandler } from '@timber-js/app/cache';
-
-export default new MemoryCacheHandler();
-```
-
-The default export is the `CacheHandler` instance. Export `cdnPurge` as a named export for CDN purge handlers. The default handler is in-memory. See [Caching](/docs/caching) for Redis, KV, and custom handlers.
-
-## `clientJavascript`
-
-Control whether client-side JavaScript is included in the build. Useful for static content sites, documentation, and marketing pages that don't need interactivity.
-
-```ts title="timber.config.ts"
-// Disable all client JS
-export default {
-  output: 'static',
-  clientJavascript: false,
-};
-```
-
-```ts title="timber.config.ts"
-// No client JS in production, but keep HMR in dev
-export default {
-  output: 'static',
-  clientJavascript: { disabled: true, enableHMRInDev: true },
-};
-```
-
-| Value                                      | Behavior                                                    |
-| ------------------------------------------ | ----------------------------------------------------------- |
-| `true` (default)                           | Client JS enabled — hydration, SPA navigation, etc.         |
-| `false`                                    | All client JS disabled. No hydration, no SPA navigation.    |
-| `{ disabled: true, enableHMRInDev: true }` | No client JS in production, but HMR still works in dev.     |
-
-Server actions still work — HTML forms submit natively via POST without JavaScript.
-
-## All Options
-
-| Option              | Type                        | Default                      | Description                              |
-| ------------------- | --------------------------- | ---------------------------- | ---------------------------------------- |
-| `output`            | `'server' \| 'static'`     | `'server'`                   | Output mode                              |
-| `debug`             | `boolean`                   | `false`                      | Enable timber debug logging in prod      |
-| `buildDir`          | `string`                    | `'.timber/dist'`             | Build output directory                   |
-| `clientJavascript`  | `boolean \| object`         | `true`                       | Control client-side JS                   |
-| `adapter`           | `TimberPlatformAdapter`     | —                            | Deployment adapter                       |
-| `serverTiming`      | `'detailed' \| 'total' \| false` | `'detailed'` / `'total'` | Server-Timing header                     |
-| `allowedOrigins`    | `string[]`                  | —                            | CORS / CSRF allowed origins              |
-| `csrf`              | `boolean`                   | `true`                       | CSRF protection                          |
-| `limits`            | `object`                    | —                            | Request body size limits                 |
-| `actions`           | `object`                    | —                            | Server action behavior                   |
-| `forms`             | `object`                    | —                            | Form handling (sensitive field stripping) |
-| `pageExtensions`    | `string[]`                  | `['tsx', 'ts', 'jsx', 'js']` | File extensions for pages                |
-| `slowRequestMs`     | `number`                    | `3000`                       | Slow request warning threshold (ms)      |
-| `renderTimeoutMs`   | `number`                    | `30000`                      | Render abort timeout (ms)                |
-| `devBrowserLogs`    | `string`                    | `'warn'`                     | Forward browser console to server in dev |
-| `dev`               | `object`                    | —                            | Dev-mode options                         |
-| `budget`            | `object`                    | —                            | Build-time performance budgets           |
-| `appDir`            | `string`                    | auto-detected                | Override app directory location          |
-| `mdx`               | `object`                    | —                            | MDX remark/rehype plugins                |
-| `actionEncryption`  | `object`                    | —                            | Server action bound args encryption      |
-| `reactCompiler`     | `boolean \| object`         | `true`                       | React Compiler auto-memoization          |
-| `sitemap`           | `object`                    | —                            | Auto-generated sitemap.xml               |
-| `clientSegmentCache`| `boolean`                   | `false`                      | Opt-in client segment cache for partial nav |
-| `topLoader`         | `object`                    | enabled                      | Navigation progress bar                  |
-
-For the full type definition, see the [Config API Reference](/docs/api-config).
-
-## .gitignore
-
-Add these to your `.gitignore` — they're generated at build/dev time and should not be committed:
-
-```txt title=".gitignore"
-.timber
-.content-collections
-```
-
-`.timber` contains the build output (default `.timber/dist`). `.content-collections` contains generated modules from [content collections](/docs/content-collections). `create-timber-app` adds both automatically.