@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/docs/api/36-cli.mdx

@@ -0,0 +1,143 @@
+---
+title: 'CLI'
+description: 'timber dev, build, preview, check, and init commands.'
+slug: 'cli'
+---
+
+# CLI
+
+timber.js provides four commands. All are thin wrappers around Vite with timber-specific behavior.
+
+```tsx
+timber < command > [--config<path>];
+```
+
+## Commands
+
+### `timber dev`
+
+Start the development server with HMR and React Fast Refresh.
+
+```bash
+timber dev
+timber dev --config ./custom-vite.config.ts
+```
+
+Starts a Vite dev server with timber's routing, RSC pipeline, and dev tooling active. File changes trigger instant HMR. Route changes are detected automatically.
+
+The server binds the port immediately on startup and shows a loading page while Vite initializes. This eliminates connection refused errors during cold start.
+
+#### Port selection
+
+The default port is **`3000`** for both `timber dev` and `timber preview` (matching Next.js and most Node web frameworks). If `3000` is already in use, timber automatically bumps to `3001`, then `3002`, and so on until it finds a free port:
+
+```
+[timber] Port 3000 in use, using 3001
+```
+
+To override the default, use any of the following (highest precedence first):
+
+1. `server.port` in `vite.config.ts`
+2. `PORT=4000 timber dev` — the `PORT` environment variable
+
+> **Note:** `timber dev --port 4000` is an error, not a silent no-op. The timber CLI only accepts `--config` — use `PORT` or `server.port` to change the port.
+
+When you set the port explicitly, timber **does not** auto-bump — a conflict produces an `EADDRINUSE` error so you find out immediately rather than connecting to the wrong port. This same behavior applies to `timber preview` and the production Node preview server.
+
+### `timber build`
+
+Run the production build.
+
+```bash
+timber build
+timber build --config ./custom-vite.config.ts
+```
+
+Uses Vite's `createBuilder` + `buildApp()` to run a multi-environment build (RSC, SSR, client). The output goes to `.timber/dist/` by default (configurable via `buildDir` in `timber.config.ts`) and is shaped by your adapter (Cloudflare, Nitro, static).
+
+After the build completes, a route table is printed showing each route's type and bundle size:
+
+```tsx
+Route                          Type   Size
+─────────────────────────────────────────────
+/                              ○      2.1 kB
+/about                         ○      1.8 kB
+/blog/[slug]                   λ      3.4 kB
+/api/contact                   ƒ      0.5 kB
+
+○ Static   λ Dynamic   ƒ Function
+```
+
+### `timber preview`
+
+Serve the production build locally for testing.
+
+```bash
+timber preview
+```
+
+If your adapter provides a `preview()` method (e.g. Cloudflare's Miniflare-based preview), that takes priority. Otherwise falls back to Vite's built-in preview server.
+
+A `timber.config.ts` that exists but fails to load is a hard error naming the file — preview never silently falls back to the plain Vite preview server with your adapter ignored.
+
+Always run `timber build` before `timber preview`.
+
+### `timber check`
+
+Validate types and routes without producing build output.
+
+```bash
+timber check
+```
+
+Runs TypeScript type checking via `tsgo --noEmit`. Useful in CI pipelines and pre-commit hooks to catch type errors without a full build.
+
+### `timber init`
+
+Write `AGENTS.md` and `CLAUDE.md` to the project root for AI coding agent discovery.
+
+```bash
+timber init
+```
+
+The content comes from the installed `@timber-js/app` package, so it's always in sync with your installed version. If either file already exists, it's skipped — delete it first to regenerate.
+
+The generated `AGENTS.md` includes project structure, key imports, common patterns, and pointers to the full documentation in `node_modules/@timber-js/app/docs/`. `CLAUDE.md` is a one-line pointer to `AGENTS.md`.
+
+## Options
+
+| Flag              | Short | Description                                                                                               |
+| ----------------- | ----- | --------------------------------------------------------------------------------------------------------- |
+| `--config <path>` | `-c`  | Path to a custom Vite config file (for `dev`, `build`, `preview`) or a `tsconfig.json` path (for `check`) |
+
+> **Note:** For `timber check`, `--config` is passed to `tsgo --project` and should point to a TypeScript config file, not a Vite config.
+
+`--config` is the only flag. Any other flag produces an error rather than being silently ignored, with a hint at the supported alternative (e.g. `--port` points you to the `PORT` env var or `server.port` in `vite.config.ts`).
+
+## Package Manager Scripts
+
+Most projects run timber through package.json scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "timber dev",
+    "build": "timber build",
+    "preview": "timber preview",
+    "check": "timber check"
+  }
+}
+```
+
+```bash
+pnpm dev
+pnpm build
+pnpm preview
+pnpm run check
+```
+
+## What's Next
+
+- [Getting Started](/docs/quick-start) — create a project and run `timber dev`
+- [Configuration](/docs/api-config) — `timber.config.ts` reference
+- [Deployment](/docs/deploying) — build and deploy to production

package/docs/learn/00-introduction.mdx

@@ -0,0 +1,76 @@
+---
+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 _embraces_ the complexity of building websites. Since building a website is inherently complex, a framework that embraces that complexity will inevitably feel overwhelming at first. But I'd implore you to imagine it as a toolbelt that gives you access to each tool in the toolkit. As you understand the tools, the toolbelt falls into place.
+
+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.
+
+------
+
+This all sounds like a lot. I'm not here to say it isn't. But if you're building a serious website, 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.
+
+To learn the inherent complexity of these ideas, you internalize an architecture that can scale up and down. One that gives you access to both UX and DX that is unparalleled and not limited. Timber does not dumb down our abstractions to make it easier to _understand_, because that comes at the cost of optionality.
+
+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. You can write an inefficient website in Timber, and 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.
+
+Again, if you're new to building websites, this is a tall task.
+
+But 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 one by one.
+
+{/* 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,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 |
+| `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              # /
+```
+
+## 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 group collisions** — two route groups in the same slot that both define a page for the same URL path are caught at build time
+
+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.
+
+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).