@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

package/docs/more/50-ai-agent-instructions.mdx

@@ -1,171 +0,0 @@
----
-title: 'AI Agent Instructions'
-description: 'Structured reference for AI coding agents working with timber.js — key differences from Next.js, import paths, common mistakes, and reading order.'
-slug: 'ai-agent-instructions'
----
-
-# AI Agent Instructions
-
-This page is for AI coding agents (Claude Code, Cursor, Copilot, Codex, etc.) and developers who paste context into agent prompts. It is concise and structured for machine consumption — but useful as a quick reference for humans too.
-
-## Fetching These Docs as Markdown
-
-Any timber.js documentation page can be fetched as plain markdown by sending an `Accept: text/markdown` header:
-
-```bash
-curl -H 'Accept: text/markdown' https://timberjs.com/docs/ai-agent-instructions
-```
-
-This returns the page content as `text/markdown` with a `203` status code, suitable for piping into agent context or saving to a file.
-
-## How timber.js Docs Are Organized
-
-| Location | Purpose | Audience |
-| --- | --- | --- |
-| `packages/website/content/docs/` | User-facing guides, tutorials, API reference | Developers building with timber |
-| `design/` | Design decisions, architecture, internal specs | Contributors and agents implementing features |
-| `CLAUDE.md` | Contributor workflow, commands, code style | Agents working on timber itself |
-
-**Read the user-facing docs for building apps.** Read the design docs only when you need to understand _why_ something works the way it does or when contributing to timber itself.
-
-## Reading Order by Task
-
-**Starting a new project:**
-1. [Introduction](/docs/introduction) — what timber is and its philosophy
-2. [Quick Start](/docs/quick-start) — project setup
-3. [Pages and Layouts](/docs/pages-and-layouts) — routing basics
-4. [Configuration](/docs/configuration) — `timber.config.ts`
-
-**Adding a feature:**
-1. [API: @timber-js/app/server](/docs/api-server) — server exports
-2. [API: @timber-js/app/client](/docs/api-client) — client exports
-3. The relevant guide (caching, forms, middleware, etc.)
-
-**Debugging:**
-1. [Coming from Next.js](/docs/coming-from-nextjs) — if the code assumes Next.js patterns
-2. [The Flush Point](/docs/the-flush-point) — if status codes or headers are wrong
-3. [Error Handling](/docs/error-handling) — deny, error boundaries, status files
-
-## Key Differences from Next.js
-
-These are the things you will get wrong if you assume Next.js behavior.
-
-| Concept | Next.js | timber.js |
-| --- | --- | --- |
-| Default component type | Client components need `'use client'` | **All components are server components** by default. Only add `'use client'` when you need browser APIs or hooks. |
-| Fetch caching | `fetch()` is patched with implicit caching | `fetch()` is **never patched**. Use `cache.data()` from `@timber-js/app/cache` explicitly. |
-| ISR | `revalidate` option | **Does not exist.** Use `cache.data()` with TTL and tags. |
-| `loading.tsx` | Convention for auto-Suspense | **Does not exist.** Use `<Suspense>` explicitly. |
-| Middleware | Single global `middleware.ts` with matchers | Per-segment `middleware.ts` files + global `proxy.ts`. One-arg signature: `middleware(ctx)`. |
-| `notFound()` | `notFound()` from `next/navigation` | `deny(404)` from `@timber-js/app/server`. Sends a real HTTP 404. |
-| `redirect()` | `redirect()` from `next/navigation` | `redirect()` from `@timber-js/app/server`. Same concept, different import. |
-| Search params | Untyped `useSearchParams()` | Typed `defineSearchParams()` with Zod schemas, in any module you import. |
-| Auth pattern | In middleware or components | `access.ts` per segment with slot degradation. |
-| Forms | `useFormState` / `useFormStatus` | `createActionClient` + `useActionState` returns a 4-tuple. Forms work without JS. |
-
-## Import Map
-
-| What you need | Import from |
-| --- | --- |
-| `deny`, `redirect`, `getHeaders`, `getCookieJar`, `createActionClient` | `@timber-js/app/server` |
-| `Link`, `useRouter`, `usePathname`, `useActionState` | `@timber-js/app/client` |
-| `cache`, `CacheHandler` | `@timber-js/app/cache` |
-| `defineSearchParams` | `@timber-js/app/search-params` |
-| `defineSchema`, `InferCodecType` | `@timber-js/app/params` |
-| Content collection data | `content-collections` |
-| `Metadata` type | `@timber-js/app/server` |
-
-There is **no** `@timber-js/app` default import. Always use the subpath exports above.
-
-## Project Structure
-
-```
-app/                    # Route tree — file-system routing
-  proxy.ts              # Global request handler (like global middleware)
-  layout.tsx            # Root layout
-  page.tsx              # Home page
-  [segment]/
-    page.tsx            # Dynamic route
-    middleware.ts       # Per-segment middleware
-    access.ts           # Per-segment authorization
-    denied.tsx          # Rendered when access.ts denies
-    error.tsx           # Error boundary for this segment
-    search-params.ts    # Search param definitions (ordinary module, not a convention)
-  schema.ts             # Segment param schemas (from @timber-js/app/params)
-content/                # Content collections (outside route tree)
-timber.config.ts        # Framework configuration
-mdx-components.tsx      # Custom MDX component mappings (optional)
-content-collections.ts  # Collection definitions (optional)
-```
-
-## Common Mistakes
-
-1. **Importing from `next/*`** — there is no `next` package. Use `@timber-js/app/server` and `@timber-js/app/client`. Exception: `next/navigation`'s `redirect()` and `notFound()` are shimmed for compatibility.
-
-2. **Adding `'use client'` to everything** — components are server components by default. Only add `'use client'` when you need browser APIs, event handlers, or React hooks like `useState`/`useEffect`.
-
-   The exception: `error.tsx`, `global-error.tsx`, and component status files (`404.tsx`, `4xx.tsx`, `503.tsx`, …) **always** need `'use client'`. timber passes them to a client error boundary as a prop, so a server component there breaks every page under that segment. The build rejects it and names the file. MDX status files (`404.mdx`) are exempt.
-
-3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache.data()` from `@timber-js/app/cache` when you want caching.
-
-4. **Creating `loading.tsx` files** — this convention does not exist. Use `<Suspense>` with an explicit fallback where you want streaming.
-
-5. **Using ISR patterns** (`revalidate`, `unstable_cache`) — ISR does not exist. Use `cache.data()` with `{ ttl: seconds, tags: ['tag'] }`.
-
-6. **Calling `notFound()`** — use `deny(404)` from `@timber-js/app/server` instead. It sends a real HTTP 404 status code.
-
-7. **Putting all middleware in one file** — middleware is per-segment. Place `middleware.ts` at the route level that matches the concern. Use `proxy.ts` for global concerns.
-
-8. **Assuming `useSearchParams()` exists** — use `defineSearchParams()` in any module with Zod schemas, then access via `.get()` (server) or `.useQueryStates()` (client).
-
-## Quick Patterns
-
-### Data fetching with caching
-
-```tsx
-import { cache } from '@timber-js/app/cache';
-
-const getProducts = cache.data(
-  async () => db.products.findMany(),
-  { ttl: 300, tags: ['products'] }
-);
-
-export default async function Page() {
-  const products = await getProducts();
-  return <ProductList products={products} />;
-}
-```
-
-### 404 handling
-
-```tsx
-import { deny } from '@timber-js/app/server';
-
-export default async function Page({ params }: { params: Promise<{ id: string }> }) {
-  const { id } = await params;
-  const item = await getItem(id);
-  if (!item) deny(404);
-  return <Item item={item} />;
-}
-```
-
-### Per-segment middleware
-
-```ts title="app/dashboard/middleware.ts"
-import type { MiddlewareContext } from '@timber-js/app/server';
-
-export default async function middleware(ctx: MiddlewareContext) {
-  ctx.headers.set('X-Dashboard', 'true');
-}
-```
-
-### Access control
-
-```ts title="app/(auth)/access.ts"
-import { redirect, getCookieJar } from '@timber-js/app/server';
-
-export default async function access() {
-  const session = getSession(getCookieJar());
-  if (!session) redirect('/login');
-}
-```