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

package/docs/learn/00-introduction.mdx

@@ -0,0 +1,109 @@
+---
+title: 'Introduction'
+description: 'Why timber.js exists'
+slug: 'introduction'
+notAI: true
+---
+
+# Introduction
+
+## Basics
+
+Timber is a react-based web framework built on Vite and Server Components. It is inspired by next.js, tanstack start, and remix however it brings an independent approach built on a modern and flexible foundation.
+
+It is designed to align with web standards and attempts to use as little framework magic as possible. We feel it unlocks both the most flexible UX and DX possible. Rather than using heuristics to adjust how the framework operates, it gives you the knobs to fine-tune your website to your liking.
+
+---
+
+Here are some of the ideas that drive Timber.
+
+### Architectural Optionality
+
+Timber is a framework that aims to bring architectural optionality. All websites run in three environments:
+
+* The Server
+* The Server and the Client (often called SSR or pre-rendering)
+* The Client
+
+The server brings forth access control, privacy, and performance and sets up the initial response to the user.
+
+The client unlocks interactivity, dynamic rendering, and cross-route state.
+
+SSR and pre-rendering bridge the two.
+
+Server Components unlock each environment to its fullest capacity, while allowing you to step through them via one unified component tree. And timber embraces them fully.
+
+### Upside-Down Astro
+
+Astro is a framework built for content and it's philsophy is: static first, islands of interactivity and dynamic content.
+
+Timber is the inverse of this approach: dynamic first, with islands of static content. In our experience, most webpages require some form of dynamic rendering. Expensive stuff, cached stuff, is usually on the leafier side – a component tree here and there. Only caching subsets of your tree gives you powerful performance without sacrificing the full server functionality (access control, middleware, logging, and more).
+
+We also find this to be a simpler mental model. Requests flow through the server – subsets of the page are cached. Interactivity and state exists throughout the tree and across routes.
+
+### Serialized Building Blocks: Cookies, Search Params, Segment Params
+
+Timber takes all of the building blocks of the web that are effectively: serialize data to a string and back and it gives you the guard rails to properly type and validate them. Things like cookies, search params, and segment params.
+
+Everything is driven by standard schemas (zod, valibot, nuqs, custom, etc.) and you create factory functions to access that data on the server and the client.
+
+```tsx
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  month: z.string().optional(),
+  day: z.string().optional(),
+  slug: z.string().optional(),
+});
+
+// later on
+const sp = searchParams.get();
+
+// or on the client
+const [sp, setSearchParams] = searchParams.useQueryStates();
+```
+
+### Typed Routes
+
+All routing in timber is fully typed and integrated. So you can write a `<Link>` as:
+
+```tsx
+<Link href="/blog/[slug]" segmentParams={{ slug: 'a-post' }}>Page</Link>
+```
+
+Or just normal `<a>` tags work too.
+
+### Middleware and Access Control
+
+Timber's routing and layouting system is almost 1:1 inspired by next.js. This file based routing structure lends itself to a compositional architecture, where you can build up layers of functionality as you go deeper into the route tree.
+
+The filesystem maps directly to the route tree. On top of that, because our architecture is dynamic first, we can give you: proper middleware and `access.ts` access control.
+
+When you hit a route, every segment's `middleware.ts` and `access.ts` is executed in series. Though some would call this slow, with a proper data architecture, we find that this is rarely the bottleneck to building a fast and performant website.
+
+And the DX clarity and functionality gains are immense. Give it a try, you'll be surprised how nice it feels.
+
+### Forms
+
+Forms have long been the biggest pain point of building React apps. They are chonky, buggy, and painful to write. Timber flips forms on their head and make the whole process feel a lot more like _react_.
+
+Here are our rules for forms:
+
+1. Forms must work consistently with or without javascript
+2. Inputs must _own their own state_ or be uncontrolled – no more hoisting your logic and context above the form. This makes sure forms are composable.
+3. You should be able to have global validation and input-level validation
+4. Validation should be possible to run on either the server, or the client
+5. Forms should maintain their data if submission fails (whether you are on the JS or non-JS track)
+
+Now you might say, wow, these are a lot of rules – even though they all sound good. But to handle all of these features, you'd need way more code.
+
+Turns out – the opposite. It's way less code. It's more functional, more flexible, and you write less code to handle it all. Does the science back it up? Let's see:
+
+### Developer Clarity
+
+We believe the good UX is invisible, but good DX is _transparent_. You should always be able to see what's going on. No caching is implicit.
+
+-----
+
+These are the core tenants of Timber. It's the framework I wish existed. Thanks for taking the time to look into it.

package/docs/learn/01-quick-start.mdx

@@ -0,0 +1,94 @@
+---
+title: 'Quick Start'
+description: 'Create a timber.js project and see it running in 60 seconds.'
+slug: 'quick-start'
+notAI: true
+---
+
+# Quick Start
+
+<Callout variant="tip" title="We recommend pnpm">
+  You can use any package manager, but we personally recommend `pnpm`.
+
+  You can install pnpm with `npm install -g pnpm`.
+</Callout>
+
+## Create a Project
+
+
+```sh
+pnpm create create-timber-app my-app
+cd my-app && pnpm i
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000). You have a running app.
+
+## Project Structure
+
+```
+my-app/
+  src/
+    app/
+      layout.tsx        # Root layout — wraps every page
+      page.tsx          # Home page (/)
+      globals.css
+  timber.config.ts      # Framework configuration
+  vite.config.ts        # Vite configuration
+  package.json
+  tsconfig.json
+```
+
+The `app/` directory is your route tree. Files named `page.tsx` become pages. Files named `layout.tsx` coelesce and wrap the page. This composable structure scales very effectively.
+
+## Your First Page
+
+Every page is a server component by default — it executes exclusively on the server and produces HTML.
+
+```tsx title="app/page.tsx"
+export default function HomePage() {
+  return (
+    <div>
+      <h1>Hello, timber.js</h1>
+      <p>This page was server-rendered.</p>
+    </div>
+  );
+}
+```
+
+<Callout variant="tip" title="Server Components">
+  I know server components can seem intimidating, but I'd implore you to play with them. Even if you don't want to run a server, you can still use "server components" with distinct advantages.
+
+  You can build static SPAs or even zero-javascript websites with both server components and timber.
+</Callout>
+
+## Adding a Second Route
+
+Create `app/about/page.tsx`:
+
+```tsx title="app/about/page.tsx"
+export default function AboutPage() {
+  return <h1>About</h1>;
+}
+```
+
+Navigate to `/about` and you'll see the About page.
+
+## Navigation
+
+Links are added by importing the `Link` component.
+
+```tsx title="app/about/page.tsx"
+import { Link } from '@timber-js/app/client';
+
+export default function AboutPage() {
+  return (
+    <div>
+      <h1>About</h1>
+      <Link href="/">Go Home</Link>
+    </div>
+  );
+}
+```
+
+That's it. You now have a basic timber.js app up and running.

package/docs/learn/02-pages-and-layouts.mdx

@@ -0,0 +1,147 @@
+---
+title: 'Pages and Layouts'
+description: 'File-system routing with page.tsx, layout.tsx, and nested directory structure.'
+slug: 'pages-and-layouts'
+notAI: true
+---
+
+# Pages, Layouts, and Segments
+
+timber.js uses file-based routing, inspired directly by next.js. Folders in the `app/` directory become routes. The directory structure maps to the URL structure, which maps to your component tree.
+
+We tweaked a few things, but next's layouting and routing design is among its strongest points. This also makes it very easy to migrate to timber.
+
+## Pages
+
+A `page.tsx` file makes a route:
+
+```
+app/
+  page.tsx          # /
+  about/
+    page.tsx        # /about
+  blog/
+    page.tsx        # /blog
+```
+
+Each page exports a default component. Pages are server components by default — they can be async and fetch data directly.
+
+```tsx title="app/blog/page.tsx"
+export default async function BlogPage() {
+  const data = await fetchContent();
+
+  return <h1>{data.title}</h1>;
+}
+```
+
+## Segments
+
+Each directory beneath the `app` directory is called a `segment`. In the example above, `about` and `blog` are segments.
+
+A nested, dynamic segment would look something like: `./app/blog/[slug]/page.tsx`. In this case, `blog` and `[slug]` are the segments that make up this route pattern.
+
+## Layouts
+
+All parental `layout.tsx` files wraps a page in its subtree. Layouts receive a `children` prop and persist across navigations — they don't re-render when you navigate between sibling pages.
+
+```tsx title="app/layout.tsx"
+import type { ReactNode } from 'react';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <nav>My Site</nav>
+        <main>{children}</main>
+      </body>
+    </html>
+  );
+}
+```
+
+Layouts nest. Each directory level can have its own layout:
+
+```
+app/
+  layout.tsx          # Root layout — wraps everything
+  page.tsx            # /
+  blog/
+    layout.tsx        # Blog layout — wraps all blog pages
+    page.tsx          # /blog
+    [slug]/
+      page.tsx        # /blog/my-post
+```
+
+When you visit `/blog/my-post`, the component tree looks like:
+
+```tsx
+<RootLayout>
+  <BlogLayout>
+    <BlogPostPage />
+  </BlogLayout>
+</RootLayout>
+```
+
+The root layout shell (nav, footer) stays mounted when you navigate between blog posts. Only the innermost content re-renders.
+
+## Segment Convention Files
+
+Each directory is called a **segment** and can contain these files:
+
+| File            | What it does                                              |
+| --------------- | --------------------------------------------------------- |
+| `page.tsx`      | The leaf content for this route                           |
+| `layout.tsx`    | Persistent UI shell — wraps children, survives navigation |
+| `access.ts`     | Authorization gate — runs before the layout renders       |
+| `middleware.ts` | Pre-render hook for headers, redirects, and cache warming |
+| _(none)_        | Segment param codecs live in `app/schema.ts`; search params in any module you import — see [Typed Params](/docs/typed-params) |
+| `error.tsx`     | Error boundary catching failures in this subtree          |
+| `404.tsx`       | Denial page for 404 status code (must be a client component) |
+
+None are required. A segment with just `layout.tsx` provides shared UI. One with just `page.tsx` is a leaf route.
+
+<Callout variant="tip" title="No loading.tsx">
+  You'll notice there's no `loading.tsx` file. This is intentional and by design.
+
+  We'll learn more about _why_ later on.
+</Callout>
+
+## Route Groups
+
+Directories wrapped in parentheses create a segment boundary without affecting the URL:
+
+```
+app/
+  (marketing)/
+    page.tsx            # /
+    about/
+      page.tsx          # /about
+  (dashboard)/
+    layout.tsx          # Dashboard layout (shared sidebar, etc.)
+    settings/
+      page.tsx          # /settings
+```
+
+Use groups to organize by concern — auth boundaries, public vs private areas, or custom layout structures — without polluting URLs.
+
+## Private Folders
+
+Prefix a directory with `_` to exclude it from routing:
+
+```
+app/
+  _components/          # Not a route — co-locate shared code here
+    Button.tsx
+  page.tsx              # /
+```
+
+## Deterministic Route Discovery
+
+timber produces build errors for ambiguous route configurations:
+
+- **Duplicate convention files** — `page.tsx` and `page.jsx` in the same directory is an error, not a silent winner-by-filesystem-order
+- **Route collisions** — two pages (or a page and a `route.ts`) that answer the same URL are caught at build time. Routes are compared by the URLs they match, not by how they are spelled: `x/(a)/[id]/page.tsx` and `x/(b)/[slug]/page.tsx` collide, and so do `x/(a)/page.tsx` and `x/(b)/[[...rest]]/page.tsx`, since an optional catch-all also matches with zero segments. Different segment _kinds_ don't collide — `[id]` beside `[...rest]` is ordered deterministically and keeps building
+
+This behavior is deterministic regardless of filesystem `readdir` order. In Next.js, the result of these ambiguities depends on the OS and filesystem, which can produce different behavior between local development and CI.
+
+For dynamic segments, advanced routing patterns (parallel routes, intercepting routes, catch-all segments), and API routes, see [Advanced Routing](/docs/advanced-routing).

package/docs/learn/03-fetching-data.mdx

@@ -0,0 +1,211 @@
+---
+title: 'Fetching Data'
+description: 'Async server components, deny(404), and dynamic segments.'
+slug: 'fetching-data'
+notAI: true
+---
+
+# Fetching Data
+
+```ts title="app/schema.ts" id="schema" hidden
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': codec.string,
+  },
+});
+
+declare function fetchProducts(opts: { take: number }): Promise<{ id: string; name: string }[]>;
+```
+
+Timber and RSCs do not prescribe _where you must_ fetch data. They only give you _more optionality_ as to where.
+
+**You** (the developer) can decide where and when you want to fetch data (whether it be the server, or the client, or at build-time). Let's walk through each.
+
+Server components are async — in general, this is the first place to reach for data fetching (or querying).
+
+```tsx title="app/page.tsx"
+export default async function HomePage() {
+  const products = await fetchProducts({ take: 10 });
+
+  return (
+    <ul>
+      {products.map((p) => (
+        <li key={p.id}>{p.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Though it might feel confusing at first, you'll find that it's *often* the best place to fetch your data. It fits cleanly into the request/response model, prevents client-side waterfalls, and is generally the _fastest_ round-trip. Though there _will_ be scenarios where data fetching in other places (i.e. the client) make more sense depending on each context. Don't be afraid to mix and match data fetching, this is the whole point of timber: optionality.
+
+## Dynamic Segments
+
+Wrap a directory name in brackets to create a dynamic segment that captures a URL parameter:
+
+```
+app/
+  products/
+    [id]/
+      page.tsx          # /products/42, /products/abc
+```
+
+Access the param with `getSegmentParams()`. Import `SEGMENT_PATH` from `$segment` for exact types:
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+declare function getProduct(id: string): Promise<{ name: string; description: string } | null>;
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+
+  if (!product) return deny(404);
+
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <p>{product.description}</p>
+    </div>
+  );
+}
+```
+
+`deny(404)` sends a real HTTP 404 — not a 200 with an error message. Search engines, CDNs, and `curl -f` all see the correct status code. Other status codes, status-code files, and error boundaries are covered in [Error Handling](/docs/error-handling).
+
+For typed params (numbers, UUIDs, enums), define codecs in `app/schema.ts`. See [Typed Params](/docs/typed-params).
+
+## Server Components Span Three Environments
+
+React Server Components split your code into three worlds:
+
+**Server components** (default) — run on the server only. Their code never reaches the client. You can `await` database queries, access secrets, import heavy libraries. Zero client-side JavaScript cost.
+
+**Client components** (`'use client'`) — run in the browser (and on the server for the initial HTML render). Use them for `useState`, `useEffect`, event handlers, and browser APIs.
+
+**Server actions** (`'use server'`) — functions that run on the server but are callable from the client. Used for mutations — form submissions, data updates.
+
+These compose. A server component can render a client component as a child. Server actions wire the client back to the server for mutations:
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+import { AddToCartButton } from './add-to-cart';
+
+declare function getProduct(id: string): Promise<{ id: string; name: string } | null>;
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+  if (!product) return deny(404);
+
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <AddToCartButton productId={product.id} />
+    </div>
+  );
+}
+```
+
+```tsx title="app/products/[id]/add-to-cart.tsx"
+'use client';
+
+import { useState } from 'react';
+
+export function AddToCartButton({ productId }: { productId: string }) {
+  const [added, setAdded] = useState(false);
+  return (
+    <button onClick={() => setAdded(true)}>
+      {added ? 'Added ✓' : 'Add to Cart'}
+    </button>
+  );
+}
+```
+
+The product page renders on the server (zero JS cost). The button hydrates on the client for interactivity.
+
+## No Implicit Caching
+
+`fetch()` is never patched or cached. A bare `fetch()` call hits the network every time. If you want cross-request caching, use `timber.cache()` — see [Caching](/docs/caching). If you want single-request caching, use `React.cache`.
+
+Timber will never try to optimize your code through _magic_. If you want to build an efficient website, you'll have to understand when and where to place your caching or optimizations.
+
+## Parallel Data Fetching
+
+Fetch multiple things concurrently with `Promise.all`:
+
+```tsx title="app/dashboard/page.tsx"
+declare function getUser(): Promise<{ name: string }>;
+declare function getStats(): Promise<{ revenue: number }>;
+declare function getNotifications(): Promise<{ id: string; text: string }[]>;
+
+export default async function DashboardPage() {
+  const [user, stats, notifications] = await Promise.all([
+    getUser(),
+    getStats(),
+    getNotifications(),
+  ]);
+
+  return (
+    <div>
+      <UserHeader user={user} />
+      <StatsGrid stats={stats} />
+      <NotificationList items={notifications} />
+    </div>
+  );
+}
+```
+
+## `React.cache` for Request Deduplication
+
+If multiple components in the same request need the same data, use `React.cache`:
+
+```tsx title="lib/data.ts"
+import { cache } from 'react';
+
+declare function fetchUser(id: string): Promise<{ id: string; name: string; email: string }>;
+
+export const getUser = cache(async (id: string) => {
+  return fetchUser(id);
+});
+```
+
+This deduplicates within a single request. For cross-request caching with TTL, use `timber.cache()` — see [Caching](/docs/caching).
+
+## Streaming Secondary Content
+
+Primary content fetches outside `<Suspense>` — it can affect the status code. Secondary content goes inside `<Suspense>` — it streams after the shell flushes.
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { Suspense } from 'react';
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+declare function getProduct(id: string): Promise<{ id: string; name: string } | null>;
+declare function ProductHeader(props: { product: { name: string } }): React.ReactElement;
+declare function ReviewsSkeleton(): React.ReactElement;
+declare function ProductReviews(props: { productId: string }): React.ReactElement;
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+  if (!product) deny(404);
+
+  return (
+    <div>
+      <ProductHeader product={product} />
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <ProductReviews productId={product.id} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+`getProduct` runs before the flush — if it fails, you get a real 404. Reviews stream in after. More on this in [The Flush Point](/docs/the-flush-point).

package/docs/learn/04-access-control.mdx

@@ -0,0 +1,115 @@
+---
+title: 'Access Control: access.ts'
+description: 'Per-segment access control with access.ts, deny(), and graceful slot degradation.'
+slug: 'access-control'
+notAI: true
+---
+
+# Access Control
+
+```ts title="app/schema.ts" id="schema" hidden
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+
+import { getCookieJar, redirect } from '@timber-js/app/server';
+
+declare function getSessionFromCookie(jar: ReturnType<typeof getCookieJar>): { userId: string } | null;
+declare function getUser(userId: string): Promise<{ id: string; name: string }>;
+
+
+export default defineSchema({
+  segmentParams: {
+    '[projectId]': codec.string,
+  },
+});
+```
+
+Most websites use access control of some kind. Instead of DRY-ing your access control or duplicating checks across your codebase, timber provides a _composable_ form of access control: `access.ts`.
+
+If you place an `access.ts` file anywhere in your route tree, every sub-route will execute every `access.ts` in its parental tree.
+
+You can `redirect`, `deny`, or otherwise gate access to an entire route group.
+
+## `access.ts`
+
+```ts title="app/(authenticated)/access.ts"
+import { getCookieJar, redirect } from '@timber-js/app/server';
+
+export default async function access() {
+  const session = getSessionFromCookie(getCookieJar());
+
+  if (!session) return redirect('/login');
+
+  const user = await getUser(); // getUser is wrapped in React.cache
+
+  if (!user.isVerified) return deny(401);
+}
+```
+
+`access.ts` is a gate — it passes or fails. Return values are discarded. If it doesn't throw or redirect, rendering proceeds.
+
+`access` runs before a route's layout or page in sequence, so if it short-circuits, those components are never executed.
+
+## Sharing Data Between Access and Layout
+
+Access checks and layouts share the same `React.cache` scope. Call the same cached function in both — the layout gets a free cache hit:
+
+```tsx title="app/(authenticated)/layout.tsx"
+export default async function AuthLayout({ children }: { children: React.ReactNode }) {
+  const user = await getUser(); // Cache HIT — access.ts already resolved this
+
+  return (
+    <div>
+      <nav>{user.name}</nav>
+      <main>{children}</main>
+    </div>
+  );
+}
+```
+
+## Nested Access Checks
+
+Deeper segments add their own `access.ts` for additional authorization:
+
+```ts title="app/(authenticated)/projects/[projectId]/access.ts" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+declare function requireUser(): Promise<{ id: string; orgId: string }>;
+declare function getProject(id: string): Promise<{ orgId: string } | null>;
+
+export default async function access() {
+  const user = await requireUser(); // Cache HIT from parent
+  const { projectId } = getSegmentParams(SEGMENT_PATH);
+  const project = await getProject(projectId);
+  if (!project) deny(404);
+  if (project.orgId !== user.orgId) deny(); // Default 403
+}
+```
+
+Access runs root-to-leaf. If the root gate fails, deeper gates never execute.
+
+`deny()` defaults to `403`; pass a status code (`deny(404)`, `deny(401)`) to change it. How the status code becomes a rendered page is covered in [Error Handling](/docs/error-handling).
+
+## Slot Degradation
+
+When `access.ts` denies a parallel route (slot), only that slot degrades — the page continues rendering:
+
+```
+app/
+  dashboard/
+    layout.tsx           # Receives { children, admin }
+    page.tsx
+    @admin/
+      access.ts          # Checks admin role
+      page.tsx           # Admin panel
+      denied.tsx         # Shown when access fails
+```
+
+If the user isn't an admin, `@admin` renders `denied.tsx` while the rest of the dashboard loads normally.
+
+When access denies, that segment's `layout.tsx` never runs — `denied.tsx` renders in its place, wrapped only by layouts above the denying `access.ts`. This holds at every level of a slot's tree: a nested `@admin/reports/access.ts` denial prevents `@admin/reports/layout.tsx` from executing (and from fetching data it would serialize into the response).
+
+## Middleware vs Access
+
+`access.ts` runs inside the React tree, so it has `React.cache` and supports slot degradation. `middleware.ts` runs before rendering, for headers, redirects, and cache warming. The full comparison is in [Middleware](/docs/middleware).