@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/docs/learn/05-the-flush-point.mdx

@@ -0,0 +1,175 @@
+---
+title: 'The Flush Point'
+description: 'When timber commits the HTTP status code, why there is no loading.tsx, and how Early Hints keep it fast.'
+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.
+
+## You Might Not Need A `loading.tsx`
+
+Most React frameworks push you towards building page-level skeletons or loading states. Though it's entirely trivial to build out that experience with timber, we nudge you away from that for several reasons.
+
+This is not referring to loading states on things like mutations (like submitting a form) or other actions. This is referring to initial (server) or secondary (client) page loading.
+
+This is how we as frontend engineers make browsing the web a less anxiety-inducing experience.
+
+### Loading States Are an Extra Class of UI to Maintain
+
+You have to design loading states. Decide between spinners and skeletons, and then mimic your UI in the skeleton.
+
+### Loading States Cause Content Layout Shift
+
+Loading states are fixed and content is most often dynamic both in size (think text length) and count (think number of rows). So even if you work incredibly hard to avoid major CLS, you'll invariably end up with CLS somewhere.
+
+### Loading States Are a Flash of UI
+
+Loading states are inherently temporary, so this adds flashes of content. This causes anxiety as the page spasms before finally reaching an undetermined final state. The user is left in a daze wondering if the page is finally ready.
+
+Every possible "finite state" of UI is another that you and the user have to keep in context. You'll be _surprised_ how much simpler a website feels when a page has one major representation, vs several.
+
+### Loading States Hide Prior Context
+
+Go to an old PHP site and click a URL. The _browser_ shows a loading state, but the prior page remains visible. The new page only becomes visible once it is ready. There's little advantage to hiding the past context while the user waits for the new context to load.
+
+### timber Includes a Global Route-Based Loading State
+
+On every route change, timber triggers a global page-level toploader loading state. If you want to add a secondary loading state that dims the prior content, you can easily do so.
+
+### Loading States Break JavaScript Disabled Requests
+
+`curl` a page with a `loading.tsx` and you'll get back a shell, not the content. Though people downsell the cost, it genuinely does hinder both SEO and agentic requests.
+
+Leaning on the web as intended is always better than assuming _all_ consumers have JavaScript enabled. Plus, sticking JavaScript in between your _hot_ rendering path is _inherently_ slower. It's just not necessary when you adopt a comprehensive web architecture like React Server Components.
+
+### Loading States Break Status Codes
+
+Loading states flush before the content is even fetched. This feels _faster_, but you are flushing before you know if the user is authenticated, the data exists, or any other class of issue. By flushing immediately, you are forced to send a 200 and lean on JavaScript-injected meta tags to signify errors.
+
+This breaks the contract of the web for any consumer that isn't a human. Use real status codes, you will gain downstream benefits from doing so.
+
+### Most Loading States Paper Over a Bad Data Architecture
+
+People often use loading states because their database is poorly optimized, or 50ms away from their rendering server, or otherwise. With a well designed data infrastructure, you can often fetch your data plenty fast to render your entire page in < 100ms.
+
+And when you can't, you can stream and flush those rare pages trivially.
+
+### Loading States Still Have Value, but More-So as Opt-In Secondary or Tertiary Content
+
+To add a loading state as a small sub-section of a page is trivial – just wrap your component in `<Suspense>` and you can defer slower, lower priority content.
+
+If you decide you want a full page level loading state, you can wrap your layout or page in `<Suspense>` on a case by case basis. No `loading.tsx` needed.
+
+--------
+
+A `loading.tsx` forces your flush point up ever so slightly, but you give up all the things above. Instead, timber asks you to place `<Suspense>` boundaries yourself – thereby _explicitly_ opting into the flush point.
+
+Now you get a calm, performant website that doesn't have immense content-layout-shift, doesn't hide prior content during loading, and can return proper status codes. The `loading.tsx` seems innocent enough, but its cost both cognitively and architecturally is high.
+
+------
+
+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 — see [Streaming](/docs/streaming) for how to place those boundaries.
+
+## 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 based on the build manifest. 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/06-typed-params.mdx

@@ -0,0 +1,275 @@
+---
+title: 'Typed Params'
+description: 'Codecs, segment params, search params, and cookies — typed values that cross boundaries.'
+slug: 'typed-params'
+---
+
+# Typed Params
+
+Values that cross boundaries — URL path segments, query strings, cookies — arrive as strings. timber provides a unified system for parsing them into typed values using **codecs**.
+
+## Codecs
+
+A codec converts between string values and typed values:
+
+```ts
+interface Codec<T> {
+  parse(value: string | string[] | undefined): T;
+  serialize(value: T): string | string[] | null; // string[] for repeated keys
+}
+```
+
+Any object with `parse` and `serialize` is a valid codec. You can use Zod schemas, [nuqs](https://nuqs.47ng.com/) parsers, or write your own. Standard Schema objects (Zod, Valibot, ArkType) are auto-detected — no wrapper needed.
+
+## Segment Params
+
+Dynamic segments (`[id]`, `[slug]`) capture raw strings from the URL. Define codecs in a global `app/schema.ts` to coerce them into typed values:
+
+
+```ts title="app/schema.ts" id="schema"
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+import { z } from 'zod/v4';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': z.coerce.number().int().positive(),
+    '[artistSlug]': codec.string,
+    '[year]': codec.integer,
+  },
+});
+```
+
+<Callout variant="tip" title="Auto-generated Schema Sync">
+  You can auto-generate this file at any time (or any incremental updates) by running `npx timber schema sync`.
+</Callout>
+
+Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`, `[[...slug]]`). A dynamic segment with no key here defaults to `string`. Invalid values produce a **404** — if `/products/abc` can't parse `abc` as a positive integer, the resource doesn't exist.
+
+Each dynamic segment gets one codec. If you want two different schemas for a dynamic segment, give it another name. For example: if you want `[id]` to be `number` in one place, but `uuid` in another – rename the latter to `[uuid]`.
+
+Every dynamic segment key must be unique across segment types (dynamic, catch-all, optional-catch-all). That means `[id]` and `[...id]` will throw a build error. That way, we can be sure `const { id } = getSegmentParams();` is either a flat or array value. Change the latter to `[...ids]` to fix it.
+
+### Type Narrowing with `$segment`
+
+Each route directory gets a generated `./$segment` module that exports `SEGMENT_PATH` — a string literal typed to the segment's tree path (how it's generated and the `tsconfig` setup are in [Typed Routes](/docs/typed-routes)). Pass it to `getSegmentParams()` for exact types:
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH); // id: number — narrowed!
+  const product = await getProduct(id);
+  // ...
+}
+```
+
+Without `SEGMENT_PATH`, `getSegmentParams()` returns `Partial<AllSegmentParams>` — all params optional, honest types. With `SEGMENT_PATH`, you get exact types for the current route depth.
+
+Coercion runs **after route matching, before middleware**. Middleware and access checks receive already-typed params.
+
+### Client Usage
+
+Use `useSegmentParams()` with the same `SEGMENT_PATH` pattern in client components:
+
+```tsx title="app/products/[id]/breadcrumb.tsx" use="schema"
+'use client';
+import { SEGMENT_PATH } from './$segment';
+import { useSegmentParams } from '@timber-js/app/client';
+
+export function ProductBreadcrumb() {
+  const { id } = useSegmentParams(SEGMENT_PATH);
+  return <span>Product {id}</span>;
+}
+```
+
+`SEGMENT_PATH` flows from server → client via RSC serialization — it's just a string.
+
+### Shared Components
+
+Pass `SEGMENT_PATH` as a prop for type-safe shared components:
+
+```tsx title="components/year-header.tsx"
+import { getSegmentParams } from '@timber-js/app/server';
+
+export function YearHeader({ segmentPath }: { segmentPath: string }) {
+  const { artistSlug, year } = getSegmentParams(segmentPath);
+  return <h1>{artistSlug} — {year}</h1>;
+}
+```
+
+### Without Type Narrowing
+
+Omit the argument to get all params as optional:
+
+```tsx
+import { getSegmentParams } from '@timber-js/app/server';
+
+const params = getSegmentParams();
+// ^ Partial<AllSegmentParams> — all optional, honest types
+```
+
+## Search Params
+
+Declare typed search params with `defineSearchParams` in any module, then import it where you need it. Unlike segment params, there is no convention file and nothing is scanned:
+
+```ts title="app/products/search-params.ts" id="search-params"
+import { defineSearchParams, withDefault } from '@timber-js/app/search-params';
+import { parseAsInteger } from 'nuqs';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: withDefault(parseAsInteger, 1),
+  sort: z.enum(['price', 'name', 'date']).default('date'),
+  q: z.string().optional(),
+});
+```
+
+### Server Usage
+
+```tsx title="app/products/page.tsx" use="search-params"
+import { searchParams } from './search-params';
+
+export default async function ProductsPage() {
+  const { page, sort, q } = searchParams.get();
+  const products = await getProducts({ page, sort, query: q });
+  return <ProductList products={products} />;
+}
+```
+
+### Client Usage
+
+```tsx title="app/products/filters.tsx" use="search-params"
+'use client';
+import { searchParams } from './search-params';
+
+export function ProductFilters() {
+  const [params, setParams] = searchParams.useQueryStates();
+
+  return (
+    <div>
+      <input
+        value={params.q ?? ''}
+        onChange={(e) => setParams({ q: e.target.value })}
+      />
+      <select
+        value={params.sort}
+        onChange={(e) => setParams({ sort: e.target.value })}
+      >
+        <option value="date">Date</option>
+        <option value="price">Price</option>
+        <option value="name">Name</option>
+      </select>
+    </div>
+  );
+}
+```
+
+By default, `.useQueryStates()` triggers an RSC navigation when params change. Set `shallow: true` to update the URL without a server roundtrip.
+
+## Cookies
+
+Define typed cookies with `defineCookie()`:
+
+```ts title="lib/cookies.ts"
+import { defineCookie } from '@timber-js/app/cookies';
+import { z } from 'zod/v4';
+
+export const themeCookie = defineCookie('theme', {
+  codec: z.enum(['light', 'dark', 'system']).default('system'),
+  httpOnly: false,
+  maxAge: 60 * 60 * 24 * 365,
+});
+```
+
+Server:
+
+```tsx
+const theme = await themeCookie.getCookie();   // 'light' | 'dark' | 'system'
+await themeCookie.setCookie('dark');            // before flush only
+```
+
+Client:
+
+```tsx
+'use client';
+import { themeCookie } from '../lib/cookies';
+
+export function ThemeToggle() {
+  const [theme, setTheme] = themeCookie.useCookie();
+  return (
+    <select value={theme} onChange={(e) => setTheme(e.target.value as typeof theme)}>
+      <option value="light">Light</option>
+      <option value="dark">Dark</option>
+      <option value="system">System</option>
+    </select>
+  );
+}
+```
+
+{/* ## Built-in Codecs
+
+timber ships zero-dependency codecs for common types:
+
+| Codec                       | Type              | Example                   |
+| --------------------------- | ----------------- | ------------------------- |
+| `parseAsString`             | `string \| null`  | `?q=shoes` → `'shoes'`   |
+| `parseAsInteger`            | `number \| null`  | `?page=2` → `2`          |
+| `parseAsFloat`              | `number \| null`  | `?price=9.99` → `9.99`   |
+| `parseAsBoolean`            | `boolean \| null` | `?debug=true` → `true`   |
+| `parseAsStringEnum(values)` | `T \| null`       | `?sort=price` → `'price'` |
+
+For segment params, use the `codec` namespace:
+
+| Codec              | Type                    | Description              |
+| ------------------ | ----------------------- | ------------------------ |
+| `codec.string`     | `string`                | Default (no-op passthrough) |
+| `codec.integer`    | `number`                | Integer coercion         |
+| `codec.slug`       | `string`                | URL-safe slug            |
+| `codec.stringArray` | `string[]`             | For catch-all segments   |
+| `codec.catchAll(inner)` | `T[]`             | Wraps scalar codec for catch-all segments |
+| `codec.optionalCatchAll(inner)` | `T[] \| undefined` | Wraps scalar codec for optional catch-all segments |
+
+Use `withDefault()` to get a non-nullable type for search params. [nuqs](https://nuqs.47ng.com/) parsers all work as codecs: an absent param is `null` and a repeated one takes the first value. Note that `parseAsArrayOf` reads a comma-separated list from a single key — for repeated keys (`?ids=1&ids=2`) use an array schema, e.g. `z.array(z.string()).default([])`. */}
+
+## Composition
+
+Compose codec maps via plain object spread:
+
+```ts title="lib/search-params/pagination.ts"
+import { withDefault } from '@timber-js/app/search-params';
+import { parseAsInteger } from 'nuqs';
+
+export const pagination = {
+  page: withDefault(parseAsInteger, 1),
+  pageSize: withDefault(parseAsInteger, 20),
+};
+```
+
+```ts title="app/products/search-params.ts"
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { pagination } from '@/lib/search-params/pagination';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  ...pagination,
+  sort: z.enum(['asc', 'desc']).default('asc'),
+});
+```
+
+## URL Key Aliasing
+
+Map a property name to a different URL key with `withUrlKey`:
+
+```ts
+import { defineSearchParams, withUrlKey } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  query: withUrlKey(z.string().nullable().default(null), 'q'),
+});
+// ?q=shoes → { query: 'shoes' }
+```
+
+For the full codec protocol, array codecs, and custom codec guidelines, see the [API: Search Params](/docs/api-params) reference.

package/docs/learn/07-typed-routes.mdx

@@ -0,0 +1,108 @@
+---
+title: 'Typed Routes'
+description: 'Build-time route types — <Link> validates href, $segment narrows params to the current route.'
+slug: 'typed-routes'
+---
+
+# Typed Routes
+
+timber.js generates route types at build time. `<Link>` type-checks `href` against your actual route tree, and every route directory gets a `$segment` module that narrows params to that route. This page covers what the codegen gives you; defining and reading params is covered in [Typed Params](/docs/typed-params).
+
+## How It Works
+
+When you run `timber dev` or `timber build`, the framework scans your `app/` directory and generates a route map in `.timber/routes.d.ts`:
+
+```ts
+// .timber/routes.d.ts (generated, gitignored)
+export interface TimberSegmentParams {
+  '/': {};
+  '/products/[id]': { id: number };
+  '/blog/[...slug]': { slug: string[] };
+}
+```
+
+Types reference your `app/schema.ts` codecs directly, so they stay in sync automatically.
+
+## Typed `<Link>`
+
+`<Link>` validates `href` against the route map. Invalid routes are caught at build time:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>           // ✓ known route
+<Link href="/nonexistent">Bad</Link>        // ✗ TypeScript error
+```
+
+For dynamic routes, pass `segmentParams`:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/products/[id]" segmentParams={{ id: 42 }}>
+  Product
+</Link>
+// → <a href="/products/42">Product</a>
+```
+
+Or use an interpolated href directly:
+
+```tsx
+<Link href={`/products/${id}`}>Product</Link>
+```
+
+Both forms are type-safe. With the pattern form (`/products/[id]`), `segmentParams` is required and typed. With the interpolated form, `segmentParams` is forbidden.
+
+### Search params on `<Link>`
+
+Build search params from a `defineSearchParams` definition. `buildSearchParams` type-checks the values and applies the definition's codecs and URL-key aliases:
+
+```tsx
+import { searchParams } from './search-params';
+
+<Link
+  href="/products/[id]"
+  segmentParams={{ id }}
+  searchParams={searchParams.buildSearchParams({ sort: 'newest', q: 'boots' })}
+/>
+// → /products/42?sort=newest&search=boots   (q is aliased to search)
+```
+
+A plain object also works as an untyped escape hatch for one-off params with no definition — but it skips codecs and aliases, so do not use it for keys a definition owns.
+
+## `$segment` and `SEGMENT_PATH`
+
+Each route directory gets a generated `$segment` module. It exports `SEGMENT_PATH`, a string literal typed to that directory's position in the route tree. Passing it to `getSegmentParams()` / `useSegmentParams()` narrows the result to exactly the params that exist at that depth:
+
+```tsx
+// app/products/[id]/page.tsx
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  // id is typed from your schema codec (e.g., number for codec.integer)
+}
+```
+
+Without `SEGMENT_PATH`, params are `Partial<AllSegmentParams>` — every param optional.
+
+`$segment` also exports `ROUTE`, the URL pattern with route groups stripped (e.g. `'/products/[id]'`).
+
+### tsconfig.json
+
+Add `rootDirs` so TypeScript can resolve `$segment` imports:
+
+```jsonc
+{
+  "compilerOptions": {
+    "rootDirs": [".", ".timber/types"]
+  }
+}
+```
+
+## Codegen
+
+Types are generated during `timber dev` (on startup and when routes change) and `timber build`. The generated `.timber/routes.d.ts` is gitignored — it's a build artifact. Run `timber dev` once to get types for your editor.
+
+For the generated type shapes and context types (`RouteContext`, `MiddlewareContext`, `AccessContext`), see the [TypeScript API Reference](/docs/api-typescript).