@timber-js/app 0.2.0-alpha.154 → 0.2.0-alpha.156

package/docs/learn/00-introduction.mdx

@@ -0,0 +1,81 @@
+---
+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 more modern foundation.
+
+It is built on 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.
+
+That means it is entirely possible to write an inefficient website with timber, however, you will also _understand_ exactly what is happening and have clear eyes on how to fix it.
+
+We believe that the best UX is often invisible, but the best DX is _transparent_. You shouldn't ever be confused about where something is running and why.
+
+Timber is not a framework that comes with the simplest mental model – rather it embraces the _inherent complexity_ of the web and gives you the tools to define your boundaries as you see fit. Server and client, static and dynamic, build-time and run-time. So on and so forth. There is no one true _best_ place to put these boundaries, so it is incumbent on the developer to _choose_ where to place them.
+
+Timber is a tool for frontend professionals. Though a beginner could pick it up and learn both the framework and the platform (the web) incrementally, it is best utilized by people who have a deep understanding of both the web and building websites.
+
+Think of it as a flexible toolbelt of tools: the mental model to understand each of these tools and how to use them is high, but once you do, the framework clicks into place. A simpler mental model may come with it an easier skill curve, but at the sacrifice of both user experience and developer experience.
+
+Timber is understandable, but you'll have to be patient in understanding it. We feel it's worth the investment.
+
+## Philosophy
+
+All web frameworks are created out of some basic philosophies of how its creators feel websites should be built. Timber is no exception.
+
+Here's ours:
+
+A good web architecture in 2026 can scale up and down with the requirements of the project. That doesn't mean a simple target (e.g. a static blog) comes with it the simplest mental model, but that it can be functionally deployed in the most efficient manner. And that same architecture can scale up to a complex, dynamic website, both from a structural and a deployment perspective.
+
+A good web architecture _embraces_ the complexity of building websites. Since building a website is inherently complex, a framework that embraces that complexity will feel complex and overwhelming at first. But it is easier to imagine it as a toolbelt that gives you access to each tool in the belt.
+
+So while a beginner could pick up this framework, and it could incrementally teach them each component of building a powerful website, this framework is _not_ designed to be the simplest mental model. This is a framework for the frontend professional. Or a team building a complex and powerful web experience. People who want to understand:
+
+* how the server and client co-exist (the network boundary)
+* the distinction between build-time and request-time
+* static routes and dynamic routes co-existing
+* zero-javascript websites and fully static js-only SPAs
+* how to build a composable architecture that still feels like it sits on web standards
+
+Now this all sounds like a lot. I'm not here to say it isn't. But if you're a frontend professional, if you work on a team of experienced engineers, an architecture that sits across these complexities and doesn't abstract them gives you the power to define your boundaries: server and client, static and dynamic, client js and not.
+
+You have to learn the inherent complexity of these ideas, but once you do, you internalize an architecture that can scale up and down. One that gives you access to both UX and DX that is unparalleled. Timber does not dumb down our abstractions to make it easier to _understand_, because that comes at the cost of optionality. It gives you the tools to _define_ your boundaries.
+
+Other frameworks that have pursued this have either abstracted away too much, leaned on too much magic, or ignored web standards. Timber is _not_ smarter than you. It doesn't try to be. If you write an inefficient website in Timber, it won't stop you. But it also won't project onto you _how_ to build a website. It just gives you the foundation to control it yourself.
+
+The good news is, you don't have to understand this all immediately. You can layer on your understanding one by one. And I promise, in the long-term it will click. But you may have to touch it yourself for it to click.
+
+
+{/* Here are our basic philosophies:
+
+- All websites sit somewhere across three environments. Embracing these three as first-party targets is a bid for developer autonomy, not confusion.
+  - Server
+  - Client
+  - Isomorphic (Universal SSR)
+- Serverless is a flawed paradigm for rendering
+  - Though it can be useful at times, owning your _own_ server (and CPU cycles) will always be more performant and cost effective at anything beyond a basic scale
+  - An inefficiency in serverless means an unbounded/infinite bill, on a server it only means degraded performance
+  - A server means your database can live _next_ to your rendering layer, which will always outperform _holistic_ edge rendering in generic real-world scenarios
+- Your framework should never be smarter than you
+  - Good UX is invisible, good DX is transparent
+  - It's better to be understandable than magic, which means performance is fine tunable – rather than automatic
+- The web constantly serializes and deserializes strings, the framework should provide typing and parsing to those edges
+  - Search Params
+  - Cookies
+  - Segment URL Params
+  - and more...
+- A good web-framework scales horizontally across your surface API (routes)
+  - Adding more routes or components shouldn't affect performance on others
+- A good web framework has finely-tuned control over static (build-time) and dynamic (run-time) rendering
+- A good web framework has the ability to scale up and down functionally and with developer clarity, which means deploying a website that:
+  - Can ship zero client javascript
+  - Can ship static content
+  - And can scale up to a completely dynamic website */}
+
+More here soon...

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,138 @@
+---
+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 |
+| `params.ts`     | Typed search params definitions (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              # /
+```
+
+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.
+
+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/03b-access-control.mdx

@@ -0,0 +1,130 @@
+---
+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()`
+
+`deny()` produces the correct HTTP status code and renders the matching status file:
+
+```ts
+deny();      // 403 Forbidden (default)
+deny(404);   // 404 Not Found
+deny(401);   // 401 Unauthorized
+```
+
+## 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
+
+|               | `middleware.ts`                        | `access.ts`                       |
+| ------------- | -------------------------------------- | --------------------------------- |
+| Runs          | Before rendering                       | Inside React tree                 |
+| Purpose       | Lightweight checks, redirects, headers | Auth, data gating                 |
+| `React.cache` | Not available                          | Active — shares scope with layout |
+| Slots         | N/A                                    | Graceful degradation              |
+
+Use `middleware.ts` for headers, redirects, and cache warming. Use `access.ts` for auth — it has access to `React.cache` and supports slot degradation.