# Goribu

> A full-stack React framework for Cloudflare Workers, built for humans and coding agents.

---

# Introduction

Source: https://goribu.dev/docs

Goribu is a full-stack React framework for Cloudflare Workers.

The Workers stack is not only one of the most powerful and complete ones out there, but also very attractive cost-wise. Building with it is straightforward, but if you come from Next.js, Express.js, or Remix v2, you have to adopt a lot of new conventions. So Goribu aims to make it more familiar and delightful to build production apps there.

To achieve this, the key decisions were:

- **Choosing the happy path for building apps,** which means simplicity and speed of change over complex optimizations before it’s needed. Your code should be elegant, even if you are not writing it anymore.
- **Making what the platform offers as easy as possible to use,** without configuring the same things over and over. (Global D1 read replicas, free CDN, etc.)
- **Adjusting to the new AI coding paradigm** and targeting to solve new challenges like understanding the code while allowing your agents to code and provision resources.

## How?

Simplicity doesn’t mean not modern or less production-ready. You get a server-driven app architecture with the initial load and SEO benefits, combined with app-like navigation for the next requests. But without client-side caches to mutate, skeleton UI or RSC. Together with your React page components being in the same file as their handlers, you can add or improve your app’s features without having to change a bunch of files.

## Human / AI Fit

While this started as a way for humans to write code, its architecture makes it really great for coding with AI agents:

- **The API surface is minimal** compared to most popular frameworks so it’s very lightweight in the context of each session.
- **There is one canonical way to do things,** so what you would write is what your AI will write too. As a resut, you can always check your code and know what is happening.
- **The ability to provision resources with a single entries** in your config, without having to use the dashboard means your coding agent can do it too for you.

All of this makes AI coding with Goribu a token-efficient and smooth experience, that works great with Codex, Claude Code and other AI agents.

If you are looking for a new way to create applications on Cloudflare, go ahead and give it a try to see for yourself.

---

# At a glance

Source: https://goribu.dev/docs/at-a-glance

A one-page overview of the basics for every part of Goribu, with examples for developers and coding agents.

## Serving pages

A Goribu app deploys one Worker plus static assets. A route's handlers run on the server and its default export is the React page. Here's an example with some sample data:

**src/routes/posts/\[id\].tsx**

```tsx
import type { Handler } from "goribu/server";

type Post = { id: string; title: string; body: string };
type Props = { post: Post };

// The server function that runs and passes props to the page
export const GET: Handler<Props> = (req, res) => {
  const posts = [
    { id: "42", title: "Hello Goribu", body: "Your first page." },
  ];
  const post = posts.find((post) => post.id === req.params.id);

  if (!post) return res.notFound();

  return res.render({ post });
};

// The React page component
export default function PostPage({ post }: Props) {
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </article>
  );
}
```

**src/routes/posts/\[id\].jsx**

```jsx
// The server function that runs and passes props to the page
export const GET = (req, res) => {
  const posts = [
    { id: "42", title: "Hello Goribu", body: "Your first page." },
  ];
  const post = posts.find((post) => post.id === req.params.id);

  if (!post) return res.notFound();

  return res.render({ post });
};

// The React page component
export default function PostPage({ post }) {
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </article>
  );
}
```

- **Initial request:** Dynamic pages stream HTML on the first visit.
- **Client navigation:** After hydration, navigation fetches JSON to update the page and its data.
- **Static candidates:** A page without HTTP handlers becomes static automatically if its URL is known at build time, no middleware applies to it, and it has not opted out explicitly.
- **Static delivery:** Successful pre-renders use Static Assets and are served by the CDN, for free. They also still hydrate and can be interactive.
- **API-only routes:** Export handlers without a React page component to create an API-only route.
- **Prebuilt 404:** Unknown URLs also receive a prebuilt 404 page from Static Assets, so scanners probing missing files do not invoke the Worker.

Read [Rendering](/docs/rendering) for static pages, request-time rendering, and hydration.

## CLI basics

Use Node.js 22+ and pnpm. Create an app, then install its dependencies from the new directory:

**Terminal**

```sh
pnpm create goribu@latest my-app
cd my-app
pnpm install
pnpm dev
```

**Terminal**

```sh
pnpm create goribu@latest my-app --js
cd my-app
pnpm install
pnpm dev
```

| Command | What it does |
| --- | --- |
| `pnpm create-goribu my-app` | Creates a new Goribu TS app. |
| `pnpm dev` | Starts the local development server. |
| `pnpm exec goribu cloudflare-login` | Logs in to Cloudflare through Wrangler. |
| `pnpm run deploy` | Builds and deploys the app to Cloudflare. |

See [Installation](/docs/installation) for setup and the full command list.

## TypeScript

- **Default language:** New Goribu apps use TypeScript with strict type checking configured.
- **JavaScript starter:** You can create a JavaScript project with `pnpm create goribu@latest my-app --js`.
- **Type checking:** Run `pnpm typecheck` before deploying TypeScript apps. Development and production builds compile TypeScript without running the type checker automatically.
- **Public types:** Goribu includes types for handlers, middleware, metadata and forms. Use `import type` for types such as `Handler` and `Middleware` from `goribu/server`.
- **Config language:** Configuration stays in `goribu.config.js` in both JavaScript and TypeScript projects.

See [Installation](/docs/installation#create-an-app) for starter options and [the API reference](/docs/api-reference) for available types.

## Routes

- **Route location:** Routes are files inside `src/routes/`. A file's path determines its URL.
- **Index routes:** An `index` file serves its containing folder.
- **Dynamic segments:** Square brackets capture a dynamic parameter.

| File | URL |
| --- | --- |
| `src/routes/index.tsx` | `/` |
| `src/routes/about.tsx` | `/about` |
| `src/routes/posts/index.tsx` | `/posts` |
| `src/routes/posts/[id].tsx` | `/posts/42`, with `req.params.id` equal to `"42"` |

- **File extensions:** Routes support `.js`, `.jsx`, `.ts`, and `.tsx`.
- **Path parameters:** Read dynamic segments from `req.params`.
- **Query parameters:** Read query strings with `req.query.get("name")`.

See [Routes](/docs/routing) for route matching and supported file patterns.

## Forms and req.body

`<Form method="post">` submits to the current route's `POST` handler. Its render child exposes submission state:

**src/routes/greet.tsx**

```tsx
import type { Handler } from "goribu/server";
import { Form } from "goribu";

type Result = { greeting: string };

export default function Greet() {
  return (
    <Form<Result> method="post">
      {({ pending, errors, data }) => (
        <>
          <label>Name <input name="name" /></label>
          <p>{errors?.name}</p>
          <p>{errors?.root}</p>

          <button disabled={pending}>Greet me</button>
          <p>{data?.greeting}</p>
        </>
      )}
    </Form>
  );
}

export const POST: Handler = async (req, res) => {
  const { name } = await req.body() as Record<string, unknown>;

  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }

  return res.json({ greeting: `Hello, ${name.trim()}!` });
};
```

**src/routes/greet.jsx**

```jsx
import { Form } from "goribu";

export default function Greet() {
  return (
    <Form method="post">
      {({ pending, errors, data }) => (
        <>
          <label>Name <input name="name" /></label>
          <p>{errors?.name}</p>
          <p>{errors?.root}</p>

          <button disabled={pending}>Greet me</button>
          <p>{data?.greeting}</p>
        </>
      )}
    </Form>
  );
}

export const POST = async (req, res) => {
  const { name } = await req.body();

  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }

  return res.json({ greeting: `Hello, ${name.trim()}!` });
};
```

- **Form methods:** Set `method` to `get`, `post`, `put`, `patch`, or `delete` to call the matching route handler.
- **Submission state:** `Form` exposes `pending`, `errors`, and `data`. After hydration, submissions update the form without reloading the page.
- **Body parsing:** Always await `req.body()`. It parses JSON requests and form fields.
- **Form fields:** Both form encodings return field objects. Uploads are `File` values, repeated names become arrays and missing fields are absent. Validate field values.
- **Validation result:** Return `res.invalid()` to expose errors keyed by field name.
- **JSON result:** Return `res.json()` to pass a successful result to `data`.
- **Redirect result:** Return `res.redirect("/posts")` after a successful submission to navigate to another page.
- **Form history:** Add `replace` to `<Form>` to replace the current history entry on navigation, so Back skips pages such as a completed login form.

Read [Forms](/docs/forms) for submission behavior and [Request handlers](/docs/handlers#reading-the-body) for body parsing.

## Client navigation

Use `Link` for client-side navigation. For the post route above:

**TSX**

```tsx
import { Link } from "goribu";

// Navigate without a full page reload after hydration.
export default function HomePage() {
  return <Link href="/posts/42">Read the first post</Link>;
}
```

**JSX**

```jsx
import { Link } from "goribu";

// Navigate without a full page reload after hydration.
export default function HomePage() {
  return <Link href="/posts/42">Read the first post</Link>;
}
```

- **Link prefetch:** Your app's internal links prefetch on intent, like on hover over or press of a link, by default. Set `prefetch={false}` to disable it.
- **Link history:** Use `<Link href="/reports?view=chart" replace>Chart</Link>` when switching views should replace the current history entry, so Back leaves the screen instead of retracing view changes.
- **UI imports:** Import `Link`, `NavLink` and `navigate` from `goribu`.

`NavLink` adds active state for menus. Use `isActive` for styling and `end` for an exact pathname match:

**Active links**

```tsx
import { NavLink } from "goribu";

<nav>
  <NavLink href="/" end>Home</NavLink>
  <NavLink
    href="/posts"
    className={({ isActive }) => isActive ? "active" : undefined}
  >
    Posts
  </NavLink>
  <NavLink href="/settings" end>Settings</NavLink>
</nav>
```

**Active links**

```jsx
import { NavLink } from "goribu";

<nav>
  <NavLink href="/" end>Home</NavLink>
  <NavLink
    href="/posts"
    className={({ isActive }) => isActive ? "active" : undefined}
  >
    Posts
  </NavLink>
  <NavLink href="/settings" end>Settings</NavLink>
</nav>
```

Use `navigate()` when navigation follows an event without a link. You can also refresh a Worker-rendered page after a mutation:

**Event navigation**

```ts
import { navigate } from "goribu";

export async function onSetupComplete() {
  await navigate("/dashboard", { replace: true });
}

export async function onDataSaved() {
  await navigate(location.href);
}
```

**Event navigation**

```js
import { navigate } from "goribu";

export async function onSetupComplete() {
  await navigate("/dashboard", { replace: true });
}

export async function onDataSaved() {
  await navigate(location.href);
}
```

See [Links & navigation](/docs/navigation) for active links, history, and page refreshes.

## Metadata

Each page can set its own metadata through a `meta` export. For shared document tags, like the viewport and favicon, use `_document`. Page metadata can be a plain object:

**Static metadata**

```tsx
export const meta = {
  title: "About",
  description: "How our team builds on Cloudflare.",
  canonical: "https://example.com/about",
  robots: "index,follow",
};

export default function AboutPage() {
  return <main>About us</main>;
}
```

**Static metadata**

```jsx
export const meta = {
  title: "About",
  description: "How our team builds on Cloudflare.",
  canonical: "https://example.com/about",
  robots: "index,follow",
};

export default function AboutPage() {
  return <main>About us</main>;
}
```

Metadata can also be a synchronous function receiving the same props as the page and its URL. For a post route, like the one earlier, add:

**Dynamic metadata**

```tsx
import type { Meta } from "goribu";

type Props = { post: { title: string } };

export const meta: Meta<Props> = ({ props: { post } }) => ({
  title: post.title,
  description: `Read ${post.title} on our blog.`,
});
```

**Dynamic metadata**

```jsx
export const meta = ({ props: { post } }) => ({
  title: post.title,
  description: `Read ${post.title} on our blog.`,
});
```

See [Rendering](/docs/rendering#page-metadata) for metadata options and document setup.

## Styling

- **Tailwind:** The starter has Tailwind configured so utility classes work immediately.
- **Plain CSS:** Edit `src/styles/global.css` or import CSS from a page or component.
- **Style delivery:** Goribu delivers the current page's styles, including on client navigation.

See [Styling and assets](/docs/rendering#styling-and-assets) for CSS, Tailwind, and public files.

## Middleware

Middleware runs on the server before the requested route's handler or page. Default-export a function from `_middleware.ts` to apply it to routes in that folder and its subfolders. For example, this adds a request ID header to responses from the posts routes:

**src/routes/posts/\_middleware.ts**

```ts
import type { Middleware } from "goribu/server";

const requestId: Middleware = (req, res) => {
  res.headers({ "x-request-id": crypto.randomUUID() });
};

export default requestId;
```

**src/routes/posts/\_middleware.js**

```js
const requestId = (req, res) => {
  res.headers({ "x-request-id": crypto.randomUUID() });
};

export default requestId;
```

- **Middleware context:** Middleware receives the same `req` and `res` as the route and may be async.
- **Continue:** Return nothing from middleware to continue to the route. There is no `next()`.
- **Stop:** Returning a `res.*` result, such as `res.redirect("/login")`, responds immediately and stops the chain.
- **Pass data:** You can attach values to `req`, for example `req.user = user` and then read them in the handler.
- **Middleware order:** Parent-folder middleware runs first.
- **Rendering impact:** Middleware keeps all affected pages on the Worker. Put it in the folder that needs it so you don't disable pre-rendering for static pages.

See [Middleware](/docs/handlers#middleware) for scope, execution order, and passing request data.

## Cookies

Use `req.cookies` to read, set and delete cookies in handlers or middleware. Goribu adds cookie changes to the returned response automatically, including redirects. This route keeps a counter in the browser's cookies:

**src/routes/visits.ts**

```ts
import type { Handler } from "goribu/server";

export const GET: Handler = (req, res) => {
  const visits = Number(req.cookies.get("visits") ?? "0") + 1;

  req.cookies.set("visits", String(visits), {
    path: "/",
    maxAge: 86400,
    httpOnly: true,
    sameSite: "Lax",
  });

  return res.json({ visits });
};
```

**src/routes/visits.js**

```js
export const GET = (req, res) => {
  const visits = Number(req.cookies.get("visits") ?? "0") + 1;

  req.cookies.set("visits", String(visits), {
    path: "/",
    maxAge: 86400,
    httpOnly: true,
    sameSite: "Lax",
  });

  return res.json({ visits });
};
```

- **Cookie example:** Visit `/visits` and reload to see the counter increase.
- **Cookie reads:** `get()` returns a string or `null` for a missing cookie.
- **Cookie options:** Options are explicit. In this example, `path: "/"` makes the cookie app-wide and `maxAge` keeps it for a day.
- **Cookie deletion:** Call `req.cookies.delete("visits", { path: "/" })` from a handler or middleware. Match the path and domain that was used when setting it, if either was specified.

See [Cookies](/docs/handlers#cookies) for cookie methods and options.

## Server code and errors

- **Page environments:** Page components run on the server and in the browser.
- **Private helpers:** Keep helpers such as `src/lib/posts.server.ts` outside `src/routes/` and import them from handlers or middleware.
- **Server boundary:** For better protection, Goribu rejects browser code importing a `.server.*` module.
- **Public props:** Anything passed through `res.render()` reaches the browser. Pass only data the page should expose.
- **Background work:** Call `req.waitUntil(promise)` in handlers or middleware for work that may continue after the response, such as logging or cache updates.
- **Missing resource:** If a resource is not found, return `res.notFound()`.
- **Error pages:** Customize `src/routes/_404.tsx` for missing pages and `_500.tsx` for unhandled production errors.
- **Error diagnostics:** Development shows details for errors, while production logs the error with an ID and passes the ID to the error page.

Read [Server-only work](/docs/handlers#server-only-work) for private helpers and [Errors](/docs/errors) for custom error pages.

## Environment variables

For local development, put your values in `.env` at the project root, then run `pnpm dev`:

**.env**

```dotenv
PUBLIC_API_URL=https://api.example.com
STRIPE_KEY=local-test-key
```

- **In handlers or middleware:** Read the private key with `req.env.STRIPE_KEY`.
- **In browser code:** Read the public URL with `import.meta.env.PUBLIC_API_URL`. Only values prefixed with `PUBLIC_` are available this way. They are included in the browser bundle, so never use this prefix for actual secrets.

For production, put your production values in `.env.production` before running `pnpm run deploy`:

**.env.production**

```dotenv
PUBLIC_API_URL=https://api.example.com
STRIPE_KEY=your-production-key
```

Deployment uploads the file's values as Worker secrets. Your code still reads server values through `req.env`. Public values are also embedded during the build.

If you prefer to manage server secrets in Cloudflare, add them to your Worker's **Settings \> Variables and Secrets**, choosing the **Secret** type. Goribu preserves existing secrets omitted from `.env.production`; without that file, it uses the secrets already on the Worker. See [Cloudflare's secret setup instructions](https://developers.cloudflare.com/workers/configuration/secrets/).

Browser values must be available when you build. Changing a Worker secret in the dashboard does not update `import.meta.env.PUBLIC_*` in an existing browser bundle; set the public value for the build and redeploy.

Keep real environment files out of Git. Local server values from `.env` are not uploaded to production.

See [Configuration](/docs/configuration#environment-variables) for file overrides and [production secrets](/docs/configuration#production-secrets) for deployment details.

## Cloudflare resources configuration

Declare a D1 database, a KV namespace, or both in the existing config. Keep your app's name and compatibility date:

**goribu.config.js**

```js
import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-08-31",
  database: { type: "d1", name: "my-app-db" },
  kv: { name: "my-app-kv" },
});
```

- **Local resources:** Restart development after changing bindings. Goribu supplies local stores for development.
- **Production resources:** When you deploy, Goribu reuses or creates named production resources. Local data stays separate.
- **Generated bindings:** Goribu generates Wrangler bindings. No resource IDs or separate Wrangler config are needed.

See [Configuration](/docs/configuration#resources) for resource options.

### D1 database

D1 is Cloudflare's SQLite database. With `database` configured above, use `req.d1` in handlers or middleware. Create your tables with migrations before querying them. This example assumes a `posts` table with `id` and `title` columns:

**Inside a request handler**

```ts
type Post = { id: number; title: string };

const title = "Hello Goribu";

const { lastRowId } = await req.d1`
  INSERT INTO posts (title) VALUES (${title})
`.run();

if (lastRowId === undefined) throw new Error("Missing inserted row ID.");

const post = await req.d1<Post>`
  SELECT id, title FROM posts WHERE id = ${lastRowId}
`.get();

const posts = await req.d1<Post>`SELECT id, title FROM posts`.all();
```

**Inside a request handler**

```js
const title = "Hello Goribu";

const { lastRowId } = await req.d1`
  INSERT INTO posts (title) VALUES (${title})
`.run();

if (lastRowId === undefined) throw new Error("Missing inserted row ID.");

const post = await req.d1`
  SELECT id, title FROM posts WHERE id = ${lastRowId}
`.get();

const posts = await req.d1`SELECT id, title FROM posts`.all();
```

- **SQL parameters:** Values inside `${...}` become bound SQL parameters, so input values do not require building SQL strings.
- **D1 writes:** `.run()` executes inserts, updates, and deletes and returns `{ changes, lastRowId }`.
- **Single row:** `.get()` returns one row or `null`.
- **Row list:** `.all()` returns an array of rows.
- **Scalar result:** `.value()` returns the first column of the first row or `null`.

For schema changes, run `pnpm exec goribu migrate:new "describe your change"` and add your SQL under `-- migrate:up` in the generated file. Run `pnpm exec goribu migrate` to apply pending migrations locally. Deployment applies pending production migrations automatically. Keep applied files unchanged and create a new migration for each later change.

Read [Database: D1](/docs/d1) for queries and freshness options, and [Migrations](/docs/d1#migrations) for the schema workflow.

### KV store

KV stores values by key, without tables or migrations. Use it for cached results or shared configuration when briefly stale reads are acceptable. With `kv` configured above, access it through `req.kv` in handlers or middleware.

This route reads a cached timestamp. If it is missing, it creates and stores one with a five-minute lifetime:

**src/routes/snapshot.ts**

```ts
import type { Handler } from "goribu/server";

type Snapshot = { createdAt: string };

export const GET: Handler = async (req, res) => {
  let snapshot = await req.kv.get<Snapshot>("snapshot", { type: "json" });

  if (snapshot === null) {
    snapshot = { createdAt: new Date().toISOString() };
    await req.kv.put("snapshot", JSON.stringify(snapshot), {
      expirationTtl: 300,
    });
  }

  return res.json(snapshot);
};
```

**src/routes/snapshot.js**

```js
export const GET = async (req, res) => {
  let snapshot = await req.kv.get("snapshot", { type: "json" });

  if (snapshot === null) {
    snapshot = { createdAt: new Date().toISOString() };
    await req.kv.put("snapshot", JSON.stringify(snapshot), {
      expirationTtl: 300,
    });
  }

  return res.json(snapshot);
};
```

Visit `/snapshot` to try it. `{ type: "json" }` parses the stored JSON; without that option, `get()` returns text. Missing keys return `null`. To store an object, use `JSON.stringify()` as above. `expirationTtl` is measured in seconds.

To remove a value, use `await req.kv.delete("snapshot")`. To browse keys, use `await req.kv.list()`, which returns one page at a time. Await writes and deletes before reporting success.

Reads can temporarily return an older value or `null` even after a successful write, and deleted values can remain visible briefly. The example returns the value it already has instead of reading it back. Use D1 for exact counters or flows that must reliably show a visitor their own changes.

See [KV store](/docs/kv) for storage options, pagination, and consistency details.

## Going live

Set your app's Worker name in `goribu.config.js`. With a Cloudflare account, log in from the app directory:

**Terminal**

```sh
pnpm exec goribu cloudflare-login
```

Goribu uses its installed Wrangler to open the browser authorization flow. Wrangler stores the credentials for later runs.

Then preview the production plan and deploy:

**Terminal**

```sh
pnpm check
pnpm run deploy
```

- **Check plan:** `check` shows the target Worker, resources and migrations without making changes.
- **Deploy sequence:** `deploy` builds, creates or reuses D1/KV resources, applies pending production migrations and uploads the Worker and static assets. It prints the public URL.
- **Later releases:** Run `pnpm run deploy` again to update the same Worker. Existing databases and KV namespaces are reused while local data is not uploaded.
- **Schema compatibility:** Migrations run before Worker upload. Schema changes must also work with the version currently serving requests.

Follow [Deploys](/docs/deployment) for Cloudflare setup, deployment checks, and schema changes.

---

# Installation

Source: https://goribu.dev/docs/installation

Start with a minimal React app that runs locally on the Workers runtime.

## Prerequisites

- **Local tools:** Use Node.js 22 or newer and pnpm.
- **Cloudflare account:** An account is needed only for deployment. Local development works without a login. You don't need a paid Workers plan to build and deploy with Goribu.

## Create an app

**Terminal**

```sh
pnpm create goribu@latest my-app
cd my-app
pnpm install
pnpm dev
```

**Terminal**

```sh
pnpm create goribu@latest my-app --js
cd my-app
pnpm install
pnpm dev
```

Open the local URL printed in your terminal. The starter is ready for you.

- **App name:** Use up to 50 lowercase letters, digits or hyphens. Start with a letter and end with a letter or digit. Pass a name, not a path.
- **Existing directories:** The starter generator does not overwrite an existing directory.
- **Dependency installation:** The starter generator does not install dependencies for you.

For JavaScript, add `--js`:

**Terminal**

```sh
pnpm create goribu@latest my-app --js
```

Both variants use the same framework APIs.

## Find your way around

| File | Purpose |
| --- | --- |
| `src/routes/index.tsx` | The home page. |
| `public/` | Static assets served at the site root. |
| `src/setup/_document.tsx` | Optional custom HTML document around your pages. |
| `src/setup/client-entry.js` | Required browser bootstrap and global CSS imports. |
| `src/styles/global.css` | Global styles and the Tailwind import. |
| `goribu.config.js` | App runtime, deployment, and resource settings. |
| `vite.config.js` | Vite, Goribu, and Tailwind plugins. |
| `AGENTS.md` | Project instructions for coding agents. |

Your pages and handlers go in the `src/routes` together, while reusable components can go in other folders like `src/components/`. Leave `.goribu/`, `.wrangler/`, `goribu.wrangler.jsonc`, and `node_modules/` to the tools that generate them.

## Start coding with your agent

Your agents will read the included `AGENTS.md` before changing the app. If not, just ask them to. Then describe a feature and its expected behavior. The [AI coding guide](/docs/agents) explains how to provide useful context and [At a glance](/docs/at-a-glance) there's a compact API introduction to point your agents to.

## Commands

Run commands from your app directory.

| Command | Purpose |
| --- | --- |
| `pnpm dev` | Develop locally with hot updates. |
| `pnpm typecheck` | Check TypeScript without emitting files. TypeScript starter only. |
| `pnpm build` | Build the Worker, browser assets, and static pages. |
| `pnpm check` | Inspect the production target, resources, and migrations without changing them. |
| `pnpm exec goribu cloudflare-login` | Log in to Cloudflare through Wrangler. |
| `pnpm run deploy` | Build and deploy to Cloudflare. |

- **Custom port:** Run `pnpm dev --port 5199` to use a specific port number (in this case 5199) instead of the default. The command fails if the port is already in use.
- **Network access:** Add `--host` to your `pnpm dev` to listen on every network interface. Then other devices on your network can reach the development server.
- **Persistent defaults:** Set development defaults in `vite.config.js`.

**Alternative development commands**

```sh
pnpm dev --port 5199
pnpm dev --host
```

If using npm, add `--` before script options so npm forwards them to the development server: `npm run dev -- --host` or `npm run dev -- --port 5199`.

Development and production builds compile TypeScript without type checking. Run `pnpm typecheck` separately in TypeScript projects.

Use the full **`pnpm run deploy`** command (don't forget the `run` part) to ship your app to Cloudflare. See [Deploys](/docs/deployment) when you are ready to publish.

## Write a route

Create `src/routes/hello.tsx` with the following example, then visit `/hello?name=Kate`. Use type-only imports to describe your page props and request handlers:

**src/routes/hello.tsx**

```tsx
import type { Handler } from "goribu/server";
import type { Meta } from "goribu";

type Props = { name: string };

// Read the query string and pass serializable props to the page.
export const GET: Handler<Props> = (req, res) => {
  const name = req.query.get("name")?.trim() || "friend";
  return res.render({ name });
};

export const meta: Meta<Props> = ({ props }) => ({
  title: `Hello, ${props.name}`,
});

// Render the same props on the server and in the browser.
export default function HelloPage({ name }: Props) {
  return <h1>Hello, {name}.</h1>;
}
```

**src/routes/hello.jsx**

```jsx
// Read the query string and pass serializable props to the page.
export const GET = (req, res) => {
  const name = req.query.get("name")?.trim() || "friend";
  return res.render({ name });
};

export const meta = ({ props }) => ({
  title: `Hello, ${props.name}`,
});

// Render the same props on the server and in the browser.
export default function HelloPage({ name }) {
  return <h1>Hello, {name}.</h1>;
}
```

- **Handler generics:** `Handler<Props, Env, Params>` also accepts types for Worker bindings and dynamic parameters.
- **Runtime validation:** Types describe expectations, so validate request input at runtime. The [API reference](/docs/api-reference#typescript) lists public types.

---

# AI coding

Source: https://goribu.dev/docs/agents

Your agent will get up to speed automatically so you only have to provide a clear description of what the app should do.

## Start with the project instructions

- **Project instructions:** The starter's `AGENTS.md` covers routes, handlers, forms, resources and project commands. If your tool doesn't automatically load it, ask it to read it before working. Most modern harnesses load it by default.
- **One source of guidance:** If your tool uses another instructions file, point it to `AGENTS.md`.
- **Framework overview:** [At a glance](/docs/at-a-glance) gives a practical overview of Goribu you can also point when there is confusion.
- **Documentation context:** Use **Copy page as Markdown** on any docs page to bring its contents into a chat or coding session.

## Describe the behavior

A useful request names the feature, its data and what success looks like:

`Add a feedback page where visitors enter a name and message. Store submissions in D1, show validation errors beside the fields and redirect to the feedback list after saving. Add a migration for the table.`

This maps directly to a route, a React page, a handler, a database declaration and a migration. The agent can prepare those files. Goribu supplies local resources during development and creates or reuses production resources on deployment.

For an existing feature, include its route and describe the current and desired behavior. A reproducible error is more useful than “fix the form.”

## Add your app's rules

Keep a short section in `AGENTS.md` for decisions specific to your app:

**AGENTS.md**

```md
## App conventions

- Use pnpm for package commands.
- Keep shared UI in src/components/.
- Feedback is plain text, with a maximum of 2,000 characters.
- Validate writes in server handlers.
- Run the relevant checks and pnpm build before handoff.
```

Update these rules when the app changes. When upgrading Goribu, review the starter's instructions and merge useful changes with your own rules or ask your agent to do it for you.

## Review the result

- **Change review:** Ask the agent to explain the changed behavior and the checks it ran.
- **Form checks:** Check success, validation errors, and pending state.
- **Database checks:** Inspect both the query and its migration.

**Terminal**

```sh
pnpm typecheck
pnpm build
pnpm check
```

**Terminal**

```sh
pnpm build
pnpm check
```

- **JavaScript projects:** Skip `pnpm typecheck` in JavaScript projects.
- **Read-only plan:** `pnpm check` inspects the production plan without actually changing resources.

Schema migrations and Worker deployments are separate operations. A successful build does not mean that a destructive migration is safe for existing data. See [D1 migrations](/docs/d1#migrations).

## Working in a chat

- **Code context:** If the assistant cannot read the project (is web-based, etc), provide the relevant route and related helpers.
- **Behavior context:** Include the error or desired behavior and matching docs.
- **Project context:** Include `AGENTS.md` for conventions and configuration or middleware when they affect the request.

Never paste credentials or local environment files. Describe the required variable names and use placeholder values instead.

---

# Tutorial

Source: https://goribu.dev/docs/tutorial

Build a small feedback app with a D1 table, a form, validation and a list of saved messages.

It will be a single page where visitors leave a name and a message and everyone sees the latest entries. It's tiny, but along the way you'll use every core piece of Goribu:

- **Routes and prerendering:** how a file becomes a page and when that page is built ahead of time.
- **Styling:** where global CSS lives, with a ready-made stylesheet you can copy and retheme.
- **D1 and migrations:** a real database, locally and in production.
- **Forms and validation:** saving input safely and showing helpful errors.
- **Deployment:** shipping it all to Cloudflare.

It takes about 15 minutes. You'll need Node.js 22+ and pnpm. A Cloudflare account is only needed for the very last step, if you want to deploy it.

## Create the app

Use the default TypeScript starter so the examples below can be pasted directly:

**Terminal**

```sh
pnpm create goribu@latest guestbook
cd guestbook && pnpm install && pnpm dev
```

**Terminal**

```sh
pnpm create goribu@latest guestbook --js
cd guestbook && pnpm install && pnpm dev
```

Open the URL that `pnpm dev` prints and you'll see the starter's welcome page. Leave the dev server running, and from now on, every save will show up in the browser right away.

Before changing anything, here are the only files we'll touch:

| File | What it's for |
| --- | --- |
| `src/routes/index.tsx` | The page at `/`. Every file in `src/routes/` becomes a route. |
| `src/styles/global.css` | App-wide CSS, already imported by `src/setup/client-entry.js`. |
| `goribu.config.js` | App configuration, including databases. |
| `migrations/` | SQL files that shape your database. We'll create this soon. |

## Make it yours

The starter page has done its job, so let's replace it. Open `src/routes/index.tsx` and swap its contents for a first version of the guestbook, with a couple of hardcoded messages for now:

**src/routes/index.tsx**

```tsx
export const meta = { title: "Guestbook" };

type Message = { id: number; name: string; message: string };

// Placeholder data until the database arrives.
const messages: Message[] = [
  { id: 2, name: "TJ", message: "Lovely little site!" },
  { id: 1, name: "Ryan", message: "First!" },
];

export default function GuestbookPage() {
  return (
    <main className="guestbook">
      <header>
        <h1>Guestbook</h1>
        <p>Say hello and leave a note for the next visitor.</p>
      </header>

      <h2>Recent messages</h2>
      <ul className="messages">
        {messages.map((item) => (
          <li key={item.id}>
            <strong>{item.name}</strong>
            <p>{item.message}</p>
          </li>
        ))}
      </ul>
    </main>
  );
}
```

**src/routes/index.jsx**

```jsx
export const meta = { title: "Guestbook" };

// Placeholder data until the database arrives.
const messages = [
  { id: 2, name: "TJ", message: "Lovely little site!" },
  { id: 1, name: "Ryan", message: "First!" },
];

export default function GuestbookPage() {
  return (
    <main className="guestbook">
      <header>
        <h1>Guestbook</h1>
        <p>Say hello and leave a note for the next visitor.</p>
      </header>

      <h2>Recent messages</h2>
      <ul className="messages">
        {messages.map((item) => (
          <li key={item.id}>
            <strong>{item.name}</strong>
            <p>{item.message}</p>
          </li>
        ))}
      </ul>
    </main>
  );
}
```

Save and the browser will show your guestbook instead of the welcome page. The `meta` export sets the tab title.

Notice what this page *doesn't* have: no handler, no middleware. That means, that for now, Goribu **prerenders** it, turning it into plain HTML at build time and serving it as a static asset.

## Add the style

Let's make it look good before going further. The starter already uses Tailwind, so we'll keep it and put it to work. Replace **everything** in `src/styles/global.css` with the stylesheet below. It includes the Tailwind import, so you can paste the whole thing without breaking anything:

**src/styles/global.css**

```css
@import "tailwindcss";

/* Your palette. Each --color-* also becomes a Tailwind class, like bg-accent or text-muted. */
@theme {
  --color-page: #f8fafc;
  --color-surface: #ffffff;
  --color-ink: #172033;
  --color-muted: #64748b;
  --color-line: #cbd5e1;
  --color-accent: #4f46e5;
  --color-on-accent: #ffffff;
  --color-danger: #b91c1c;
}

/* Dark mode only swaps the values; every class keeps working. */
@media (prefers-color-scheme: dark) {
  :root {
    --color-page: #0f172a;
    --color-surface: #1e293b;
    --color-ink: #e2e8f0;
    --color-muted: #94a3b8;
    --color-line: #334155;
    --color-accent: #818cf8;
    --color-on-accent: #0f172a;
    --color-danger: #f87171;
  }
}

@layer base {
  body {
    @apply bg-page text-ink font-sans leading-normal;
  }
}

/* Small named classes built from Tailwind utilities keep the JSX readable. */
@layer components {
  .guestbook {
    @apply mx-auto w-full max-w-2xl px-4 py-12;
  }

  .guestbook header p {
    @apply mt-0 text-muted;
  }

  .guestbook form {
    @apply my-8 grid gap-2 rounded-xl border border-line bg-surface p-6;
  }

  .guestbook label {
    @apply font-semibold;
  }

  .guestbook input,
  .guestbook textarea {
    @apply w-full rounded-lg border border-line bg-page p-3 text-ink;
  }

  .guestbook textarea {
    @apply min-h-28 resize-y;
  }

  .guestbook :is(input, textarea, button) {
    @apply focus-visible:outline-3 focus-visible:outline-offset-2 focus-visible:outline-accent;
  }

  .guestbook button {
    @apply mt-2 cursor-pointer justify-self-start rounded-lg bg-accent px-5 py-3 font-semibold text-on-accent disabled:cursor-wait disabled:opacity-60;
  }

  .error {
    @apply mb-2 text-sm text-danger empty:hidden;
  }

  .messages {
    @apply list-none p-0;
  }

  .messages li {
    @apply border-b border-line py-4 wrap-anywhere;
  }

  .messages li p {
    @apply mt-1 mb-0 whitespace-pre-wrap;
  }

  .empty {
    @apply text-muted;
  }
}
```

A few things are worth knowing here:

- **`@theme` is your palette.** Change `--color-accent` and the button, focus rings and links all follow. Because these are Tailwind theme values, you can also use them directly in JSX, like `className="text-accent"`.
- **`@apply` builds named classes from utilities.** The page uses short names like `guestbook` and `messages`, and the styling details stay in one place. Prefer utilities directly in your markup? That works too. Mix the two however you like.
- **Dark mode comes free.** The media query only swaps color values, so nothing else has to change.
- **No Tailwind in your app?** Tailwind is part of this app's Vite setup, not part of Goribu. If you removed it, drop the `@import` line and translate each `@apply` line into plain CSS.

## Declare the database

Hardcoded messages won't get us far, so let's add a real database. We'll use Cloudflare's D1 for that. In `goribu.config.js`, add the line below to the existing configuration, keeping the starter's other lines:

**Configuration field**

```js
database: { type: "d1", name: "guestbook-db" }
```

That line, inside `defineConfig({ ... })`, is enough for Goribu to manage a local database now and the production one later.

## Create the table

A database needs a table and tables are created with migrations: small SQL files that run in order, so your local and production databases always end up with the same shape. These are necessary only when your db schema changes. Let's generate the first one:

**Terminal**

```sh
pnpm exec goribu migrate:new create messages
```

Replace the generated file's SQL with:

**migrations/0001\_create-messages.sql**

```sql
-- migrate:up
CREATE TABLE messages (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  message TEXT NOT NULL,
  created_at TEXT NOT NULL
);

-- migrate:down
DROP TABLE messages;
```

Then apply it to your local database:

**Terminal**

```sh
pnpm exec goribu migrate
```

The `down` section drops the table and its data. Ignore it for now, as it's mainly there for development and to make the migration format explicit, not as a routine undo step.

Let's put a first message in so the page has something to show. `goribu d1` runs SQL against the same local database `pnpm dev` uses:

**Terminal**

```sh
pnpm exec goribu d1 "INSERT INTO messages (name, message, created_at) VALUES ('Goribu', 'Welcome to the guestbook!', datetime('now'))"
```

## Load real messages

Time to swap the placeholder array for the database. A page reads its data in a `GET` handler which runs on the server and passes props to the page through `res.render()`. Update the route:

**src/routes/index.tsx**

```tsx
import type { Handler } from "goribu/server";

export const meta = { title: "Guestbook" };

type Message = { id: number; name: string; message: string };
type Props = { messages: Message[] };

// Load the newest messages on every request.
export const GET: Handler<Props> = async (req, res) => {
  const messages = await req.d1<Message>`
    SELECT id, name, message FROM messages ORDER BY id DESC LIMIT 50
  `.all();

  return res.render({ messages });
};

export default function GuestbookPage({ messages }: Props) {
  return (
    <main className="guestbook">
      <header>
        <h1>Guestbook</h1>
        <p>Say hello and leave a note for the next visitor.</p>
      </header>

      <h2>Recent messages</h2>
      {messages.length ? (
        <ul className="messages">
          {messages.map((item) => (
            <li key={item.id}>
              <strong>{item.name}</strong>
              <p>{item.message}</p>
            </li>
          ))}
        </ul>
      ) : (
        <p className="empty">No messages yet. Be the first!</p>
      )}
    </main>
  );
}
```

**src/routes/index.jsx**

```jsx
export const meta = { title: "Guestbook" };

// Load the newest messages on every request.
export const GET = async (req, res) => {
  const messages = await req.d1`
    SELECT id, name, message FROM messages ORDER BY id DESC LIMIT 50
  `.all();

  return res.render({ messages });
};

export default function GuestbookPage({ messages }) {
  return (
    <main className="guestbook">
      <header>
        <h1>Guestbook</h1>
        <p>Say hello and leave a note for the next visitor.</p>
      </header>

      <h2>Recent messages</h2>
      {messages.length ? (
        <ul className="messages">
          {messages.map((item) => (
            <li key={item.id}>
              <strong>{item.name}</strong>
              <p>{item.message}</p>
            </li>
          ))}
        </ul>
      ) : (
        <p className="empty">No messages yet. Be the first!</p>
      )}
    </main>
  );
}
```

Refresh and the welcome message from the database appears.

Remember that the page was prerendered? Adding a `GET` handler means this page is no longer built ahead of time. It now renders on the Worker for **every request**, which is exactly what we want for data that keeps changing. There's no extra setting to flip: the handler is the signal.

The `req.d1` template tag turns `${...}` values into bound parameters, so values never get pasted into the SQL string. You'll see that in the next step.

## Accept new messages

Now let's give visitors the ability to write. Add Goribu's `Form` to the page and a `POST` handler next to `GET`. Start simple, with no validation yet:

**src/routes/index.tsx**

```tsx
import type { Handler } from "goribu/server";
import { Form } from "goribu";

// ...meta, types and GET stay the same...

// The server part that handles the form
export const POST: Handler<Props> = async (req, res) => {
  const fields = await req.body() as Record<string, unknown>;

  await req.d1`
    INSERT INTO messages (name, message, created_at)
    VALUES (${String(fields.name)}, ${String(fields.message)}, ${new Date().toISOString()})
  `.run();

  return res.redirect("/");
};
```

**src/routes/index.jsx**

```jsx
import { Form } from "goribu";

// ...meta, types and GET stay the same...

// The server part that handles the form
export const POST = async (req, res) => {
  const fields = await req.body();

  await req.d1`
    INSERT INTO messages (name, message, created_at)
    VALUES (${String(fields.name)}, ${String(fields.message)}, ${new Date().toISOString()})
  `.run();

  return res.redirect("/");
};
```

And in the page component between the header and the list:

**src/routes/index.tsx**

```tsx
// The React form
<Form method="post">
  {({ pending }) => (
    <>
      <label htmlFor="name">Name</label>
      <input id="name" name="name" maxLength={80} />

      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" maxLength={2000} />

      <button disabled={pending}>
        {pending ? "Sending…" : "Sign the guestbook"}
      </button>
    </>
  )}
</Form>
```

**src/routes/index.jsx**

```jsx
// The React form
<Form method="post">
  {({ pending }) => (
    <>
      <label htmlFor="name">Name</label>
      <input id="name" name="name" maxLength={80} />

      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" maxLength={2000} />

      <button disabled={pending}>
        {pending ? "Sending…" : "Sign the guestbook"}
      </button>
    </>
  )}
</Form>
```

Go ahead and try it. Here's what just happened:

- **The form posted** to the same route, so its `POST` handler ran. `req.body()` gave you the fields as a plain object.
- **The redirect** sent the browser back to `/`, which ran `GET` again with the fresh list.
- **Your own write showed up immediately.** D1's session bookmark carries it into that follow-up request, so you never see a stale list right after saving.
- **`pending`** was `true` while the request was in progress, which is why the button changed its label.

## Validate the input

Right now someone can submit an empty form or skip the browser entirely and send whatever they like. The `maxLength` attributes are a nice hint, but the protection has to come from the server making that checks. Replace `POST` handler with a version that validates first:

**src/routes/index.tsx**

```tsx
// Read and validate the submitted form, and save before redirecting.
export const POST: Handler<Props> = async (req, res) => {
  const fields = await req.body() as Record<string, unknown>;

  const name = typeof fields.name === "string" ? fields.name.trim() : "";
  const message = typeof fields.message === "string" ? fields.message.trim() : "";

  const errors: Record<string, string> = {};

  if (!name || name.length > 80) {
    errors.name = "Enter a name up to 80 characters.";
  }

  if (!message || message.length > 2000) {
    errors.message = "Enter a message up to 2,000 characters.";
  }

  if (Object.keys(errors).length) {
    return res.invalid(errors);
  }

  await req.d1`
    INSERT INTO messages (name, message, created_at)
    VALUES (${name}, ${message}, ${new Date().toISOString()})
  `.run();

  return res.redirect("/");
};
```

**src/routes/index.jsx**

```jsx
// Read and validate the submitted form, and save before redirecting.
export const POST = async (req, res) => {
  const fields = await req.body();

  const name = typeof fields.name === "string" ? fields.name.trim() : "";
  const message = typeof fields.message === "string" ? fields.message.trim() : "";

  const errors = {};

  if (!name || name.length > 80) {
    errors.name = "Enter a name up to 80 characters.";
  }

  if (!message || message.length > 2000) {
    errors.message = "Enter a message up to 2,000 characters.";
  }

  if (Object.keys(errors).length) {
    return res.invalid(errors);
  }

  await req.d1`
    INSERT INTO messages (name, message, created_at)
    VALUES (${name}, ${message}, ${new Date().toISOString()})
  `.run();

  return res.redirect("/");
};
```

`res.invalid(errors)` keeps the visitor on the form and hands those messages back to it. Let's show them. Update the form to read `errors` too:

**src/routes/index.tsx**

```tsx
<Form method="post">
  {({ pending, errors }) => (
    <>
      <label htmlFor="name">Name</label>
      <input id="name" name="name" maxLength={80} />
      <p className="error">{errors?.name}</p>

      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" maxLength={2000} />
      <p className="error">{errors?.message}</p>

      {errors?.root && <p className="error" role="alert">{errors.root}</p>}

      <button disabled={pending}>
        {pending ? "Sending…" : "Sign the guestbook"}
      </button>
    </>
  )}
</Form>
```

**src/routes/index.jsx**

```jsx
<Form method="post">
  {({ pending, errors }) => (
    <>
      <label htmlFor="name">Name</label>
      <input id="name" name="name" maxLength={80} />
      <p className="error">{errors?.name}</p>

      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" maxLength={2000} />
      <p className="error">{errors?.message}</p>

      {errors?.root && <p className="error" role="alert">{errors.root}</p>}

      <button disabled={pending}>
        {pending ? "Sending…" : "Sign the guestbook"}
      </button>
    </>
  )}
</Form>
```

Submit an empty form and each field tells you what's wrong. The `errors.root` line is for form-wide problems: calling `res.invalid("Something went wrong.")` with a string instead of an object puts that message there. It's good practice to always render it.

One thing you *didn't* have to do is escape the message. React renders it as text, so any HTML someone types shows up as harmless characters.

## Tidy up the server code

The route works, but the SQL sits inside the page file. Goribu has a convention for code that must never reach the browser: put it in a `.server` file outside `src/routes/`. Create:

**src/messages.server.ts**

```ts
import type { Handler } from "goribu/server";

// The request object every handler receives.
type Request = Parameters<Handler>[0];

export type Message = { id: number; name: string; message: string };

export function listMessages(req: Request) {
  return req.d1<Message>`
    SELECT id, name, message FROM messages ORDER BY id DESC LIMIT 50
  `.all();
}

export function saveMessage(req: Request, name: string, message: string) {
  return req.d1`
    INSERT INTO messages (name, message, created_at)
    VALUES (${name}, ${message}, ${new Date().toISOString()})
  `.run();
}
```

**src/messages.server.js**

```js
export function listMessages(req) {
  return req.d1`
    SELECT id, name, message FROM messages ORDER BY id DESC LIMIT 50
  `.all();
}

export function saveMessage(req, name, message) {
  return req.d1`
    INSERT INTO messages (name, message, created_at)
    VALUES (${name}, ${message}, ${new Date().toISOString()})
  `.run();
}
```

Back in the route, replace the local `Message` type with the imported one and update both handlers as shown below. Keep the page component, its `Form` import, and metadata as they are:

**src/routes/index.tsx**

```tsx
import type { Handler } from "goribu/server";
import { listMessages, saveMessage, type Message } from "../messages.server";

type Props = { messages: Message[] };

export const GET: Handler<Props> = async (req, res) => {
  return res.render({ messages: await listMessages(req) });
};

export const POST: Handler<Props> = async (req, res) => {
  const fields = await req.body() as Record<string, unknown>;

  const name = typeof fields.name === "string" ? fields.name.trim() : "";
  const message = typeof fields.message === "string" ? fields.message.trim() : "";

  const errors: Record<string, string> = {};

  if (!name || name.length > 80) {
    errors.name = "Enter a name up to 80 characters.";
  }

  if (!message || message.length > 2000) {
    errors.message = "Enter a message up to 2,000 characters.";
  }

  if (Object.keys(errors).length) {
    return res.invalid(errors);
  }

  await saveMessage(req, name, message);
  return res.redirect("/");
};
```

**src/routes/index.jsx**

```jsx
import { listMessages, saveMessage } from "../messages.server";

export const GET = async (req, res) => {
  return res.render({ messages: await listMessages(req) });
};

export const POST = async (req, res) => {
  const fields = await req.body();

  const name = typeof fields.name === "string" ? fields.name.trim() : "";
  const message = typeof fields.message === "string" ? fields.message.trim() : "";

  const errors = {};

  if (!name || name.length > 80) {
    errors.name = "Enter a name up to 80 characters.";
  }

  if (!message || message.length > 2000) {
    errors.message = "Enter a message up to 2,000 characters.";
  }

  if (Object.keys(errors).length) {
    return res.invalid(errors);
  }

  await saveMessage(req, name, message);
  return res.redirect("/");
};
```

Same behavior, but now the route reads like a description of the page and the database details are in one dedicated place of their own.

## Try it all locally

With `pnpm dev` still running, give it a final check:

- **Validation:** submit an empty form and check that both fields explain the problem.
- **Pending state:** send a real message and watch the button change while it saves.
- **Saving:** your message appears at the top of the list.
- **Persistence:** reload the page or peek with `pnpm exec goribu d1 "SELECT * FROM messages"`.

## Deploy

Happy with it? Let's ship it so you can see it in action:

**Terminal**

```sh
pnpm typecheck
pnpm build
pnpm exec goribu cloudflare-login
pnpm check
pnpm run deploy
```

**Terminal**

```sh
pnpm build
pnpm exec goribu cloudflare-login
pnpm check
pnpm run deploy
```

- **Read the plan first:** `pnpm check` is an optional step but it shows what will be created or changed without touching anything. Look it over before deploying.
- **Database setup:** the deploy creates the production database and applies your migration before uploading the Worker.
- **Fresh data:** your local test messages stay local. Production starts with an empty guestbook and a new database.

Open the live URL that is shown in your logs. Feel free to sign the guestbook one more time. That one's for real. 🎉

Keep in mind that this guestbook is public: anyone can post. Before sharing it widely, consider adding authentication or rate limiting.

## Where to go next

You've used every core part of Goribu. Each one has its own guide:

- [Routing](/docs/routing) for more pages and dynamic segments like `[id].tsx`.
- [Rendering](/docs/rendering) for prerendering, the Document, and metadata.
- [Forms](/docs/forms) for richer interactions and `fetch` mutations.
- [D1](/docs/d1) for queries, consistency, and schema changes.
- [Deployment](/docs/deployment) for environments and production checks.

Some ideas to extend the guestbook:

- **Delete button:** a `<Form method="delete">` with a `DELETE` handler.
- **Pagination:** read `req.query.page` in `GET` and adjust the `LIMIT`/`OFFSET`.
- **Message page:** a `src/routes/messages/[id].tsx` route that shows a single message with its date.

---

# Routes

Source: https://goribu.dev/docs/routing

A file in src/routes/ defines a URL, its page and any request handlers it needs.

## Pages and handlers

A default export is the React page. Without an explicit GET handler, Goribu renders it directly:

**src/routes/about.tsx**

```tsx
export const meta = { title: "About" };

// This page has no request-time data to load.
export default function AboutPage() {
  return <main><h1>About our app</h1></main>;
}
```

**src/routes/about.jsx**

```jsx
export const meta = { title: "About" };

// This page has no request-time data to load.
export default function AboutPage() {
  return <main><h1>About our app</h1></main>;
}
```

- **Request data:** Export a named HTTP handler when the response needs request data.
- **Page response:** Return `res.render(props)` to render the page in the same route file.
- **API endpoints:** A route with only handlers does not need a React component.

## File-based URLs

| File | URL |
| --- | --- |
| `src/routes/index.tsx` | `/` |
| `src/routes/about.tsx` | `/about` |
| `src/routes/posts/index.tsx` | `/posts` |
| `src/routes/posts/new.tsx` | `/posts/new` |
| `src/routes/posts/[id].tsx` | `/posts/42` |

- **Extensions:** Route files may use `.js`, `.jsx`, `.ts`, or `.tsx`.
- **Index routes:** An `index` file maps to its containing folder.
- **Excluded files:** TypeScript declaration files are ignored so they can be colocated.
- **Symlinks:** Route discovery does not follow symlinks.

### Static segments win

`/posts/new` matches `posts/new.tsx` before `posts/[id].tsx`.

## Dynamic parameters

Square brackets capture one URL segment. You can read the value as a string from `req.params`:

**src/routes/hello/\[name\].tsx**

```tsx
import type { Handler } from "goribu/server";

type Props = { name: string };

export const GET: Handler<Props> = (req, res) => {
  return res.render({ name: req.params.name });
};

export default function HelloPage({ name }: Props) {
  return <h1>Hello, {name}.</h1>;
}
```

**src/routes/hello/\[name\].jsx**

```jsx
export const GET = (req, res) => {
  return res.render({ name: req.params.name });
};

export default function HelloPage({ name }) {
  return <h1>Hello, {name}.</h1>;
}
```

- **Parameter names:** Dynamic parameter names may contain letters, digits and underscores. Each name must be distinct within one route.
- **Unsupported segments:** Catch-all and optional segments are not supported.

## Pre-rendered pages

To run a GET handler at build time, export `prerender = true` on a fixed-path page without middleware. This page captures the build timestamp:

**src/routes/build-info.tsx**

```tsx
import type { Handler } from "goribu/server";

type Props = { builtAt: string };

export const prerender = true;

export const GET: Handler<Props> = (req, res) => {
  return res.render({ builtAt: new Date().toISOString() });
};

export default function BuildInfoPage({ builtAt }: Props) {
  return <p>Built at {builtAt}</p>;
}
```

**src/routes/build-info.jsx**

```jsx
export const prerender = true;

export const GET = (req, res) => {
  return res.render({ builtAt: new Date().toISOString() });
};

export default function BuildInfoPage({ builtAt }) {
  return <p>Built at {builtAt}</p>;
}
```

- **Automatic candidates:** A page will be automatically pre-rendered when its URL is known at build time, has no HTTP handlers or selected middleware and has not opted out explicitly.
- **Production delivery:** After a successful pre-render, Cloudflare Static Assets serves the HTML and saved navigation data. Document loads, client navigation and prefetch avoid Worker invocations and their cost.

Pre-rendering fixes the server output at build time. The page can still hydrate, use React state and run client-side navigation.

Use a route export to make the choice explicit:

**Route option**

```tsx
export const prerender = false;
```

**Route option**

```jsx
export const prerender = false;
```

- **Opt out:** `prerender = false` keeps an otherwise static page on the Worker.
- **Require static output:** `prerender = true` requires static output and fails the build if Goribu cannot produce it.
- **GET at build time:** With `prerender = true`, GET runs during the production build instead of on each request. Visitors receive the saved page, which stays unchanged until the next build.
- **Incompatible routes:** `prerender = true` cannot be combined with non-GET handlers, dynamic segments or middleware.
- **Fixed data:** Pre-rendered HTML and navigation data share the same build-time props and metadata. Changing query strings does not rerun an explicitly pre-rendered GET handler or server metadata functions.
- **Development:** Pages use the Worker during development for freshness.
- **Build fallback:** A static candidate that cannot render at build time normally falls back to the Worker with a build message.
- **Suspense failures:** Since 0.9.3, a candidate whose `Suspense` boundary throws during the build stays on the Worker with a build warning, rather than shipping only its fallback. With `prerender = true`, the build fails.
- **Separate actions:** A static page can submit a [Form](/docs/forms) to a separate action route.

## Routing rules

- **Required exports:** Every route needs a page or at least one HTTP handler, but it can have both.
- **Conflicting routes:** Two files with the same URL shape fail the build. `posts/[id].tsx` and `posts/[slug].tsx` conflict.
- **Underscore names:** Names beginning with `_` are not URLs. Underscore-prefixed folders exclude their subtree.
- **Server helpers:** Keep `.server.*` helpers outside `src/routes/` and import them from handlers or middleware.
- **Browser code restrictions:** Route files use explicit named re-exports; `export *`, bare `.server.*` side-effect imports and direct `eval` are rejected in browser-reachable route code. See [Server-only work](/docs/handlers#server-only-work).
- **Reserved URLs:** `/_goribu/` is reserved for framework assets and protocols.
- **Public HTML:** Do not place public HTML files at URLs already owned by routes.
- **Prebuilt 404:** Since 0.9.3, `404.html` is handled by Goribu's prebuilt 404 page, so customize `_404` instead.
- **Special route files:** `_404`, `_500`, and folder-level `_middleware` have special roles under routes. See [Errors](/docs/errors) and [Request handlers](/docs/handlers#middleware).
- **App-wide Document:** The optional Document file is located separately in `src/setup/_document.tsx`. See [Rendering](/docs/rendering).

## HTTP defaults

- **GET:** A page has an implicit GET. An explicit handler answers its own method.
- **HEAD:** Goribu derives HEAD from GET when needed.
- **OPTIONS:** Automatic OPTIONS returns `204` with an `Allow` header.
- **Unsupported methods:** Goribu returns `405` for unsupported methods.
- **Unmatched URLs:** Unmatched URLs return 404. Since 0.9.3, production serves URLs that no Worker route can match from Static Assets without invoking the Worker. See [Which requests run the Worker](/docs/deployment#which-requests-run-the-worker).
- **Trailing slashes:** Trailing slashes redirect to the slash-free URL, except for `/`. Static assets use the same canonical shape.

---

# Request handlers

Source: https://goribu.dev/docs/handlers

Read the request, do server work, and return the response the user should receive.

## HTTP methods

Export a named HTTP handler from a route. Handlers receive `(req, res)` and may be async:

**src/routes/hello.ts**

```ts
import type { Handler } from "goribu/server";

// Return JSON without defining a page component.
export const GET: Handler = (req, res) => {
  return res.json({ name: req.query.get("name") ?? "friend" });
};
```

**src/routes/hello.js**

```js
// Return JSON without defining a page component.
export const GET = (req, res) => {
  return res.json({ name: req.query.get("name") ?? "friend" });
};
```

- **Supported methods:** Export `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, or `OPTIONS`.
- **Export casing:** Lowercase or mixed-case handler exports fail the build. Rename exports such as `get` to `GET`.
- **Return contract:** Return a `res.*` result, not a raw `Response`, JSX or a plain object.
- **Page responses:** A default React export adds a page. `res.render(props)` renders that page with serializable data.
- **Binary responses:** Use [`res.stream(body)`](#streaming-bytes) for binary or streamed bodies.

## Reading the request

| API | Use |
| --- | --- |
| `req.method`, `req.path` | HTTP method and URL pathname. |
| `req.url` | The absolute URL of the handled route, as a `URL`. |
| `req.params` | Dynamic path segments as strings. |
| `req.query` | `URLSearchParams`.Use `get()` or `getAll()` to access. |
| `req.headers` | The request's `Headers`. |
| `req.env` | Worker bindings and server environment values. |
| `req.cookies` | Read and queue cookies. |
| `req.d1`, `req.kv` | Request-scoped data APIs. |
| `req.cache` | JSON get/set/delete with no binding setup, see [Cache](/docs/cache). |

Use `req.url.origin` for links that must name the current host, such as an OAuth callback, instead of reading the `Host` header:

**Inside a handler**

```ts
const callback = new URL("/auth/callback", req.url.origin).href;
```

**Inside a handler**

```js
const callback = new URL("/auth/callback", req.url.origin).href;
```

- **Client navigation:** `req.url` is the target page's URL, not Goribu's internal endpoint. `req.path` and `req.query` are the target page's pathname and search parameters.
- **Build-time URLs:** A handler that runs during pre-rendering sees the build's local origin. Build absolute links on static pages from your public origin.

## Reading the body

Always await `req.body()`. Its result depends on the content type:

| Content type | Result |
| --- | --- |
| `application/json` | A JSON object; arrays and primitive roots are rejected. |
| `application/x-www-form-urlencoded` | An object of fields; repeated names become arrays. |
| `multipart/form-data` | An object of fields, with uploads as `File` values. Repeated names become arrays. |
| `text/*` | A string. |
| Empty or unsupported type | An empty object. |

Both form encodings return a field object. Validate each value before using it:

**src/routes/name.ts**

```ts
import type { Handler } from "goribu/server";

// Validate the value regardless of the form's encoding.
export const POST: Handler = async (req, res) => {
  const { name } = await req.body() as Record<string, unknown>;

  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }
  return res.json({ name: name.trim() });
};
```

**src/routes/name.js**

```js
// Validate the value regardless of the form's encoding.
export const POST = async (req, res) => {
  const { name } = await req.body();

  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }
  return res.json({ name: name.trim() });
};
```

- **TypeScript:** The `Record<string, unknown>` assertion allows field access without a runtime object check. It does not validate the body or its fields. A text body gives `undefined` for `name`, so the field validation above rejects it.
- **Missing fields:** Missing form fields are absent from the body object so reading one returns `undefined`.
- **Repeated fields:** Repeated names become arrays, including repeated files or mixed text and files.
- **Literal values:** Form values are not coerced and bracketed field names remain literal.
- **Malformed bodies:** Malformed JSON or multipart data produce a safe `400` response.
- **Raw bytes:** `await req.rawBody()` returns a `Uint8Array` for webhook signatures (like Stripe's) or custom parsing.
- **Shared body read:** `req.body()` and `req.rawBody()` share one body read. Either helper can be called first.

Handle missing, single and repeated values explicitly:

**src/routes/tags.ts**

```ts
import type { Handler } from "goribu/server";

// Accept one or several form fields named "tag".
export const POST: Handler = async (req, res) => {
  const { tag } = await req.body() as Record<string, unknown>;
  const submittedTags = tag === undefined ? [] : tag;
  const tags = Array.isArray(submittedTags) ? submittedTags : [submittedTags];

  if (tags.some((value) => typeof value !== "string" || !value.trim())) {
    return res.invalid({ tag: "Use non-empty text tags." });
  }
  return res.json({ tags: tags.map((value) => value.trim()) });
};
```

**src/routes/tags.js**

```js
// Accept one or several form fields named "tag".
export const POST = async (req, res) => {
  const { tag } = await req.body();
  const submittedTags = tag === undefined ? [] : tag;
  const tags = Array.isArray(submittedTags) ? submittedTags : [submittedTags];

  if (tags.some((value) => typeof value !== "string" || !value.trim())) {
    return res.invalid({ tag: "Use non-empty text tags." });
  }
  return res.json({ tags: tags.map((value) => value.trim()) });
};
```

## Choosing a response

| Return | Result |
| --- | --- |
| `res.render(props)` | Render this route's default page. |
| `res.json(data)` | Return JSON. |
| `res.text(body)` | Return plain text. |
| `res.stream(body)` | Send bytes from a `ReadableStream`, `ArrayBuffer`, typed array, or `Blob` (available since 0.9.2). |
| `res.invalid(errors)` | Return form validation errors, normally with status 422. |
| `res.redirect(path)` | Redirect, normally with status 303. |
| `res.notFound(props)` | Render the app's 404 page. |

You can use `res.status(code)` and `res.headers(object)` before a terminal helper:

**Response examples**

```ts
return res.status(201).headers({ "x-created": "yes" }).json({ id: 7 });
```

**Response examples**

```js
return res.status(201).headers({ "x-created": "yes" }).json({ id: 7 });
```

- **Bodyless statuses:** Statuses such as 204 cannot carry JSON or text.
- **HTML responses:** There is no `res.html()`; render a page to return HTML.

### Streaming bytes

`res.stream(body)` sends binary or streamed bytes, such as a file from R2 or a proxied `fetch` body, without buffering them:

**src/routes/avatars/\[id\].ts**

```ts
import type { Handler } from "goribu/server";

// Serve a private R2 file through an app route after checking access.
export const GET: Handler = async (req, res) => {
  const file = await req.r2.private.get(`avatars/${req.params.id}`);
  if (!file) return res.notFound();

  // Bridge Cloudflare's R2 stream declaration to the Web API stream type.
  return res
    .headers({ "content-type": file.httpMetadata?.contentType ?? "application/octet-stream" })
    .stream(file.body as ReadableStream<Uint8Array>);
};
```

**src/routes/avatars/\[id\].js**

```js
// Serve a private R2 file through an app route after checking access.
export const GET = async (req, res) => {
  const file = await req.r2.private.get(`avatars/${req.params.id}`);
  if (!file) return res.notFound();

  // Bridge Cloudflare's R2 stream declaration to the Web API stream type.
  return res
    .headers({ "content-type": file.httpMetadata?.contentType ?? "application/octet-stream" })
    .stream(file.body);
};
```

- **Content type:** `res.stream()` defaults to `application/octet-stream`. Set a different content type and any caching headers with `res.headers()`.
- **Response options:** Status, headers, and cookies apply to streams as for any other result.
- **HEAD requests:** A `HEAD` request to a streamed route receives headers without the body.
- **Text bodies:** Use `res.text()` for strings.
- **Range and ETag:** Goribu adds no range or `ETag` handling. Set those headers yourself if you need them.
- **Client navigation:** Links to handlers returning `res.stream(...)` trigger a full browser load so the browser can handle the raw response.
- **Pre-rendering:** A route that streams is never prerendered.

## Redirects

- **After a mutation:** Return `res.redirect("/posts")` to navigate after saving a form.
- **Default status:** A redirect defaults to 303, telling a native browser submission to follow with GET.
- **Hydrated Forms:** Hydrated Forms follow redirects without repeating the mutation. And that means no annoying "Re-submit the form" warnings when clicking back. 👍

For a permanent redirect, set the status explicitly:

**src/routes/old-home.ts**

```ts
import type { Handler } from "goribu/server";

// Move an old URL to its replacement.
export const GET: Handler = (req, res) => {
  return res.status(301).redirect("/");
};
```

**src/routes/old-home.js**

```js
// Move an old URL to its replacement.
export const GET = (req, res) => {
  return res.status(301).redirect("/");
};
```

## Cookies

- **Response delivery:** Cookie changes are added to the final response, including redirects.
- **Security options:** Cookie options are explicit and Goribu does not add security defaults.

**src/routes/visits.ts**

```ts
import type { Handler } from "goribu/server";

// Count visits using a cookie scoped to the whole app.
export const GET: Handler = (req, res) => {
  const visits = Number(req.cookies.get("visits") ?? "0") + 1;
  req.cookies.set("visits", String(visits), {
    path: "/",
    maxAge: 86400,
    httpOnly: true,
    sameSite: "Lax",
  });
  return res.json({ visits });
};
```

**src/routes/visits.js**

```js
// Count visits using a cookie scoped to the whole app.
export const GET = (req, res) => {
  const visits = Number(req.cookies.get("visits") ?? "0") + 1;
  req.cookies.set("visits", String(visits), {
    path: "/",
    maxAge: 86400,
    httpOnly: true,
    sameSite: "Lax",
  });
  return res.json({ visits });
};
```

- **Read:** `req.cookies.get(name)` returns a string or `null`.
- **Set options:** `req.cookies.set()` accepts `path`, `domain`, `expires`, `maxAge`, `httpOnly`, `secure` and `sameSite`.
- **Value encoding:** Encode structured or Unicode values before storing them.
- **Delete:** Use `req.cookies.delete("visits", { path: "/" })` with the same path and domain as the original cookie.
- **Trust boundary:** A cookie value supplied by the browser is input to validate, not proof of identity.

## Middleware

A default export in `_middleware.ts` runs before routes in its folder and subfolders:

**src/routes/posts/\_middleware.ts**

```ts
import type { Middleware } from "goribu/server";

// Add a diagnostic header, then continue to the route.
const requestId: Middleware = (req, res) => {
  res.headers({ "x-request-id": crypto.randomUUID() });
};

export default requestId;
```

**src/routes/posts/\_middleware.js**

```js
// Add a diagnostic header, then continue to the route.
const requestId = (req, res) => {
  res.headers({ "x-request-id": crypto.randomUUID() });
};

export default requestId;
```

- **Folder order:** Parent-folder middleware runs before child-folder middleware.
- **Continue or stop:** Return nothing from middleware to continue, or return a `res.*` result to stop. There is no `next()`.
- **Function arrays:** A middleware file can default-export an array of functions. They get executed from first to last.
- **Shared context:** Middleware and the handler share the same request and response builder.

### Passing data to the route

Attach loaded data to `req`, then read it in later middleware or the handler, for example `req.user.name`:

**src/routes/dashboard/\_middleware.ts**

```ts
import type { Middleware } from "goribu/server";

// Load the user once, then read req.user in the handler.
const loadUser: Middleware = async (req, res) => {
  const user = await findSessionUser(req);
  if (!user) return res.redirect("/login");
  req.user = user;
};

export default loadUser;
```

**src/routes/dashboard/\_middleware.js**

```js
// Load the user once, then read req.user in the handler.
const loadUser = async (req, res) => {
  const user = await findSessionUser(req);
  if (!user) return res.redirect("/login");
  req.user = user;
};

export default loadUser;
```

- **Lifetime:** Values attached to `req` last for one request.
- **Field names:** Use your own names, such as `user` or `team`. Do not overwrite Goribu's fields, such as `method`, `path`, `cookies`, or `env`.

In TypeScript, augment `AppRequestFields` once. Every `Handler` and `Middleware` then accepts those fields:

**src/request.d.ts**

```ts
import type { User } from "./lib/users";

declare module "goribu/server" {
  interface AppRequestFields {
    user?: User;
  }
}
```

This declaration file also works in JavaScript projects that use editor type checking. Keep a field optional unless the middleware that sets it applies to every route.

- **Scope and rendering:** Keep middleware scoped to routes that need it. Affected pages are always Worker-served.
- **Skipped requests:** Middleware does not run for unmatched URLs, automatic OPTIONS and 405 responses, or Goribu's file endpoints under `/_goribu/`, such as signed R2 downloads.
- **Signed downloads:** When creating a signed R2 link, authorize access before as the download endpoint does not run route middleware.
- **Navigation and uploads:** Client navigation and the start of an R2 upload run the target route's middleware.

## Server-only work

Put private helpers in `.server.ts` or `.server.js` files outside the routes folder. Import them from handlers or middleware, never from browser-reachable components.

- **Server module chains:** Server modules may import other server modules. A chain such as `report.ts → body.server.ts → images.server.ts` works normally.
- **Browser module cleanup:** Before building a route's browser module, Goribu removes its HTTP handlers, `meta`, `prerender`, and `uploads` exports, plus code only they use, including server-only initializer calls.
- **Shared helpers:** Helpers shared with the page stay in the browser module and cannot depend on a `.server.*` module.
- **Boundary enforcement:** Development and production both reject a `.server.*` import that reaches the browser code.
- **Named re-exports:** Browser-reachable route files must use explicit named re-exports. `export *` is rejected there.
- **Side effects and eval:** Bare side-effect imports such as `import "../instrument.server"` and direct `eval` are rejected in browser-reachable route files. Move them into a `.server.*` helper used only by a handler.
- **Underscore folders:** Helpers in `_`-prefixed folders are not rewritten and may use `export *`.

**src/routes/report.ts**

```ts
// Name each re-exported handler; export * is rejected in route files.
export { load as GET } from "../lib/report.server";
```

**src/routes/report.js**

```js
// Name each re-exported handler; export * is rejected in route files.
export { load as GET } from "../lib/report.server";
```

- **Background work:** Use `req.waitUntil(promise)` for work that may finish after the response.
- **Required writes:** Await writes that must succeed before telling the user their change was saved.

---

# Rendering

Source: https://goribu.dev/docs/rendering

Send useful HTML first, then hydrate the page for interaction and navigation.

## First visit and navigation

- **Direct visits:** For a Worker-served page, Goribu runs middleware and the GET handler, resolves metadata and streams HTML through the Document.
- **Page props:** A handler's `res.render(props)` supplies props for both the page and its browser hydration.

After hydration, eligible [Link](/docs/navigation) transitions request a JSON description of the next page and its data. Goribu loads the page module and its styles, updates metadata and commits the navigation. You keep writing ordinary React components and handlers.

In production, pre-rendered pages receive both HTML and client navigation data from Static Assets without invoking the Worker. They still hydrate normally. See [Routes](/docs/routing#pre-rendered-pages) for the conditions that make a page static.

## Page metadata

Export `meta` from a route. Use an object for fixed values:

**src/routes/about.tsx**

```tsx
export const meta = {
  title: "About our team",
  description: "Meet the people building this app.",
  canonical: "https://example.com/about",
  robots: "index,follow",
};

// Page content lives inside the shared Document.
export default function AboutPage() {
  return <main><h1>About our team</h1></main>;
}
```

**src/routes/about.jsx**

```jsx
export const meta = {
  title: "About our team",
  description: "Meet the people building this app.",
  canonical: "https://example.com/about",
  robots: "index,follow",
};

// Page content lives inside the shared Document.
export default function AboutPage() {
  return <main><h1>About our team</h1></main>;
}
```

Use a synchronous function when metadata depends on page props or the URL. Load data in the handler, then pass it through `res.render()`:

**Dynamic metadata**

```tsx
import type { Meta } from "goribu";

type Props = { post: { title: string; summary: string } };

// Add this export to a route that renders a post prop.
export const meta: Meta<Props> = ({ props, url }) => ({
  title: props.post.title,
  description: props.post.summary,
  canonical: new URL(url.pathname, "https://example.com").href,
  meta: [{ property: "og:type", content: "article" }],
});
```

**Dynamic metadata**

```jsx
// Add this export to a route that renders a post prop.
export const meta = ({ props, url }) => ({
  title: props.post.title,
  description: props.post.summary,
  canonical: new URL(url.pathname, "https://example.com").href,
  meta: [{ property: "og:type", content: "article" }],
});
```

- **Function contract:** A `meta` function receives `{ props, url }` and must be synchronous. Do not make it async.
- **Validation:** Metadata is validated before HTML streaming begins.
- **Navigation:** Route-owned head tags are replaced on navigation.
- **Pre-rendered metadata:** Props, URL, and metadata are captured at build time. Client navigation reuses that metadata even when query strings change.
- **Shared head tags:** Keep shared tags, such as the viewport and favicon, in the Document.
- **Metadata fields:** Supported fields are `title`, `description`, `canonical`, `robots`, `meta`, and `links`. See the [reference](/docs/api-reference#metadata).
- **Additional tags:** Use `meta` for extra name/property tags and `links` for additional link tags.
- **Duplicate tags:** Do not repeat a canonical or description in both the dedicated field and the additional tags.

## The Document

The starter supplies an optional Document in `src/setup/`. To customize it, edit `src/setup/_document.tsx`:

**src/setup/\_document.tsx**

```tsx
import { ClientEntry, Stylesheet } from "goribu";
import type { DocumentProps } from "goribu";

// Preserve the framework's head, hydration root, and browser entry.
export default function Document({ children, head, nonce }: DocumentProps) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Stylesheet />
        {head}
      </head>
      <body>
        <div id="root">{children}</div>
        <ClientEntry src="/src/setup/client-entry.js" nonce={nonce} />
      </body>
    </html>
  );
}
```

**src/setup/\_document.jsx**

```jsx
import { ClientEntry, Stylesheet } from "goribu";

// Preserve the framework's head, hydration root, and browser entry.
export default function Document({ children, head, nonce }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Stylesheet />
        {head}
      </head>
      <body>
        <div id="root">{children}</div>
        <ClientEntry src="/src/setup/client-entry.js" nonce={nonce} />
      </body>
    </html>
  );
}
```

- **Default shell:** Goribu uses its default shell when no custom Document is present.
- **Required browser entry:** `src/setup/client-entry.js` is always required.
- **Document structure:** Keep one `Stylesheet`, one `ClientEntry`, and the fixed `#root`.
- **Worker nonce:** `nonce` is available for your own inline scripts on Worker-rendered responses, including static pages rendered by the Worker in development.
- **Pre-rendered nonce:** `nonce` is `undefined` on prerendered pages, which receive no CSP header. Set `prerender = false` on a page that must have a CSP.
- **Inline scripts:** Pass `nonce={nonce}` to your inline scripts. React omits an undefined attribute, so one Document works for Worker-rendered and prerendered pages.
- **CSP configuration:** Send a CSP through `responseHeaders`. A `<meta>` tag built from `nonce` would block a prerendered page's inline scripts. See [Configuration](/docs/configuration#response-headers).
- **Entry URL:** `ClientEntry`'s `src` is the development fallback. Production resolves the hashed asset.

## Styling and assets

The starter includes Tailwind by default. Plain CSS works too:

**src/setup/client-entry.js**

```js
import "goribu/client";
import "../styles/global.css";
```

- **CSS imports:** Import CSS from `src/setup/client-entry.js`, a page or a component.
- **Style loading:** Goribu includes styles needed for the first render and loads the next page's styles during navigation.
- **Fixed asset URLs:** Put files in `public/` when they need a fixed URL. For example `public/logo.svg` is available at `/logo.svg`.
- **Imported assets:** Vite-managed imports are built into the asset graph.
- **Reserved paths:** Do not create files under `/_goribu/` or public HTML that shadows a route.

## Server and browser code

Read a browser-only API after hydration so the initial server and browser output match. This component checks the connection once when it mounts:

**src/components/connection-check.tsx**

```tsx
import { useEffect, useState } from "react";

export default function ConnectionCheck() {
  const [online, setOnline] = useState<boolean | null>(null);

  // After React has taken over
  useEffect(() => {
    setOnline(navigator.onLine);
  }, []);

  let message = "Checking…";
  if (online !== null) message = online ? "Online" : "Offline";

  return <p>{message}</p>;
}
```

**src/components/connection-check.jsx**

```jsx
import { useEffect, useState } from "react";

export default function ConnectionCheck() {
  const [online, setOnline] = useState(null);

  // After React has taken over
  useEffect(() => {
    setOnline(navigator.onLine);
  }, []);

  let message = "Checking…";
  if (online !== null) message = online ? "Online" : "Offline";

  return <p>{message}</p>;
}
```

- **Execution environments:** Page components run on the server and in the browser.
- **Browser APIs:** Use and read browser-only APIs in effects or event handlers.
- **Request-specific work:** Keep request-specific work in handlers.

Anything serialized into page props is public. Keep credentials and private SDKs in server-only modules, and return only the fields the UI needs.

---

# Links & navigation

Source: https://goribu.dev/docs/navigation

Goribu provides a few components for enhanced navigation with sensible defaults.

## Link

Import `Link` from `goribu`. It renders an anchor that works before JavaScript loads:

**Navigation links**

```tsx
import { Link } from "goribu";

// Keep normal anchor behavior such as opening a link in a new tab.
export default function Menu() {
  return (
    <nav>
      <Link href="/posts">Posts</Link>
      <Link href="/login">Sign in</Link>
      <Link href="/reports" prefetch={false}>Reports</Link>
    </nav>
  );
}
```

**Navigation links**

```jsx
import { Link } from "goribu";

// Keep normal anchor behavior such as opening a link in a new tab.
export default function Menu() {
  return (
    <nav>
      <Link href="/posts">Posts</Link>
      <Link href="/login">Sign in</Link>
      <Link href="/reports" prefetch={false}>Reports</Link>
    </nav>
  );
}
```

- **History replacement:** `replace` updates the current history entry instead of adding one.
- **Prefetch default:** `prefetch` defaults to `true`. Hovering briefly or pressing an eligible link starts loading its destination.
- **Disable prefetch:** Use `prefetch={false}` when prefetching is not useful or is costly.
- **Anchor props:** `Link` accepts normal anchor props, including `target`, `download`, and event handlers.
- **Click cancellation:** Your `onClick` runs first and can cancel navigation with `preventDefault()`.

## NavLink

The `NavLink` is useful for a menus that need active url styling:

**Active navigation**

```tsx
import { NavLink } from "goribu";

// Highlight the current section using pathname-based matching.
export default function SettingsMenu() {
  return (
    <nav>
      <NavLink
        href="/settings"
        className={({ isActive }) => isActive ? "active" : undefined}
      >
        Settings
      </NavLink>
      <NavLink href="/settings/profile" end>Profile</NavLink>
    </nav>
  );
}
```

**Active navigation**

```jsx
import { NavLink } from "goribu";

// Highlight the current section using pathname-based matching.
export default function SettingsMenu() {
  return (
    <nav>
      <NavLink
        href="/settings"
        className={({ isActive }) => isActive ? "active" : undefined}
      >
        Settings
      </NavLink>
      <NavLink href="/settings/profile" end>Profile</NavLink>
    </nav>
  );
}
```

- **Active state:** An active `NavLink` gets `aria-current="page"`. Let `NavLink` own that attribute.
- **Path matching:** Matching ignores query strings and hashes, respects segment boundaries and normally includes child paths.
- **Exact matching:** `end` requires the exact pathname. The `/` pathname is always matched exactly.

## Navigate from an event

Use `navigate()` when navigation follows an action with no meaningful anchor:

**Event handler**

```tsx
import { navigate } from "goribu";

// Continue after an application-controlled event.
export async function continueToDashboard() {
  await navigate("/dashboard", { replace: true });
}
```

**Event handler**

```jsx
import { navigate } from "goribu";

// Continue after an application-controlled event.
export async function continueToDashboard() {
  await navigate("/dashboard", { replace: true });
}
```

- **Return value:** `navigate()` returns a Promise.
- **Link semantics:** Prefer `Link` when users should be able to copy the URL, open another tab or navigate without JavaScript.

After changing data with your own `fetch`, navigate to the current URL to refresh a Worker-rendered page:

**Event handler**

```ts
await fetch(`/posts/${id}/like`, { method: "POST" });
await navigate(location.href);
```

**Event handler**

```js
await fetch(`/posts/${id}/like`, { method: "POST" });
await navigate(location.href);
```

- **Worker-rendered refresh:** Navigating to the current URL runs the page's GET handler and `meta` again, fetches fresh route data and updates the page in place.
- **State and history:** A refresh with it of the current URL keeps component state and adds no history entry. `replace` is not needed.
- **Pre-rendered refresh:** A prerendered page has fixed build-time data. Navigating to its current URL only scrolls to the top.
- **Form results:** A Form result already updates the page itself.

## Where navigation gets its data

When you follow a `Link`, call `navigate` or press Back/Forward in the browser, Goribu fetches the destination page's data and swaps it in without a full document load. Where that data comes from depends on how the destination route renders:

- **Prerendered pages** are served from Static Assets in production. The Worker does not run. The page receives the same props and metadata that were saved at build time and changing the query string does not recompute them. This also applies to prefetch and to redirects that land on a static page.
- **Dynamic pages** are requested from the Worker on every navigation, just like a document load. Middleware, GET handlers, cookies and request-scoped resources such as `req.d1` all run as usual.

If a page must reflect the current request, such as the signed-in user or the query string, make it dynamic with a handler, middleware or `prerender = false`. See [Rendering](/docs/rendering) for the rules.

In development every navigation goes through the Worker, because build-time snapshots do not exist yet. Test static behavior with a production build.

In both cases, Goribu loads the destination's JavaScript and styles before it updates the screen and URL. The data request uses an internal endpoint under `/_goribu/`. Always navigate with `Link`, `NavLink`, or `navigate` instead of calling it directly. There is no router store or navigation hook to keep in sync.

## Page state across navigation

Changing a query parameter keeps the pathname, so navigation updates the page in place and preserves its component state:

**Browser event handler**

```ts
import { navigate } from "goribu";

export async function showNotesTab() {
  const url = new URL(location.href);
  url.searchParams.set("tab", "notes");
  await navigate(url.href);
}
```

**Browser event handler**

```js
import { navigate } from "goribu";

export async function showNotesTab() {
  const url = new URL(location.href);
  url.searchParams.set("tab", "notes");
  await navigate(url.href);
}
```

- **Same-path navigation:** Query changes such as `?tab=notes`, revisiting the current URL and in-place Form renders update the page in place, preserving component state and DOM.
- **State across paths:** To keep state across different paths of the same route, put it in the URL or browser storage.

## History and scrolling

- **History entries:** Each navigation adds one history entry or replaces the current one with `replace`. A redirect chain records only its final destination.
- **Scrolling:** A new page scrolls to its hash target or to the top. Back and Forward restore the saved scroll position.
- **Current URL:** Navigating to the URL already on screen adds no history entry and scrolls to the top. A static page keeps its state without refetching while a dynamic page fetches fresh data.

## Native behavior and fallbacks

- **Browser-handled links:** Goribu handles only same-origin links. External links, downloads, `target="_blank"`, modifier clicks and same-page `#hash` links behave as usual.
- **Full-page fallback:** If a client-side transition can't complete, for example because the response is an API result or the app was redeployed, Goribu loads the page normally instead.
- **Overlapping navigations:** The latest navigation wins. A slower earlier request never replaces it.

---

# Forms

Source: https://goribu.dev/docs/forms

Write a handler, return a result and Goribu handles everything in between, so your forms feel fast and stay simple.

## A complete form

This route accepts a name and returns a greeting:

**src/routes/greet.tsx**

```tsx
import type { Handler } from "goribu/server";
import { Form } from "goribu";

type Result = { greeting: string };

// Show the current submission's state beside the field.
export default function GreetPage() {
  return (
    <Form<Result> method="post">
      {({ pending, errors, data }) => (
        <>
          <label htmlFor="name">Name</label>
          <input id="name" name="name" />
          <p>{errors?.name}</p>
          <button disabled={pending}>
            {pending ? "Sending…" : "Greet me"}
          </button>
          <p>{data?.greeting}</p>
        </>
      )}
    </Form>
  );
}

// Validate a native or enhanced submission before returning a result.
export const POST: Handler = async (req, res) => {
  const { name } = await req.body() as Record<string, unknown>;
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }
  return res.json({ greeting: `Hello, ${name.trim()}!` });
};
```

**src/routes/greet.jsx**

```jsx
import { Form } from "goribu";

// Show the current submission's state beside the field.
export default function GreetPage() {
  return (
    <Form method="post">
      {({ pending, errors, data }) => (
        <>
          <label htmlFor="name">Name</label>
          <input id="name" name="name" />
          <p>{errors?.name}</p>
          <button disabled={pending}>
            {pending ? "Sending…" : "Greet me"}
          </button>
          <p>{data?.greeting}</p>
        </>
      )}
    </Form>
  );
}

// Validate a native or enhanced submission before returning a result.
export const POST = async (req, res) => {
  const { name } = await req.body();
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }
  return res.json({ greeting: `Hello, ${name.trim()}!` });
};
```

- **Method:** `method` is required and it can be any HTTP verb.
- **Action:** Defaults to the current URL. Use `action="/another-route"` to submit elsewhere.
- **Static pages:** A mutation handler makes its page dynamic. To keep a page prerendered, put the handler in a separate route without a page component and target it with `action`.

## Choose the result

| Handler result | Enhanced submission |
| --- | --- |
| `res.json(data)` | Stay on the page and expose `data`. |
| `res.invalid(errors)` | Show errors, mark matching controls, and focus the first invalid field. |
| `res.redirect(path)` | Navigate to the destination without repeating the mutation. |
| `res.render(props)` | Render this route in place with fresh props and metadata. |

- **Default choice:** Use `res.json` for an in-place result and `res.redirect` when the next screen is another page, such as a list after saving.
- **Same-page renders:** `res.render()` works only when the action is the displayed page. From a separate action route, redirect instead. If Goribu can't confirm the match, it reloads the page with a GET rather than repeating the write.
- **History:** Add `replace` to `Form` to replace the current history entry instead of adding one.

## Validation

Pass `res.invalid()` an object whose keys match control names, or a string for a form-level error:

**Inside a handler**

```ts
return res.invalid({
  name: "Enter a name.",
  root: "The request could not be saved.",
});
```

**Inside a handler**

```js
return res.invalid({
  name: "Enter a name.",
  root: "The request could not be saved.",
});
```

- **Status:** `res.invalid()` responds with 422.
- **Form-level errors:** A string, or the `root` key, becomes `errors.root`.
- **Field matching:** Goribu matches keys to inputs by `name`, sets `aria-invalid`, and focuses the first invalid input.
- **Rendering messages:** Goribu doesn't display messages for you. Render each field error and `errors.root`.

Because Goribu sets `aria-invalid` on each matching input, a single CSS rule highlights every invalid field without extra code in your components:

**src/styles/global.css**

```css
input[aria-invalid="true"] {
  border-color: crimson;
}
```

Always leave a place for form-level messages, even if you only return field errors today:

**Form-level message**

```tsx
// Inside a Form render child, alongside your field messages:
{errors?.root && <p>{errors.root}</p>}
```

**Form-level message**

```jsx
// Inside a Form render child, alongside your field messages:
{errors?.root && <p>{errors.root}</p>}
```

Always validate input and authorization in the handler. Browser constraints are a useful first check, not a replacement for server validation.

## GET forms

Use GET for searches and filters:

**Search form**

```tsx
import { Form } from "goribu";

// Put the search term in the URL so results can be shared.
export default function SearchForm() {
  return (
    <Form method="get" action="/search" replace>
      <label htmlFor="q">Search</label>
      <input id="q" name="q" />
      <button>Search</button>
    </Form>
  );
}
```

**Search form**

```jsx
import { Form } from "goribu";

// Put the search term in the URL so results can be shared.
export default function SearchForm() {
  return (
    <Form method="get" action="/search" replace>
      <label htmlFor="q">Search</label>
      <input id="q" name="q" />
      <button>Search</button>
    </Form>
  );
}
```

- **Reading values:** Use `req.query.get("q")` in the destination's GET handler.
- **Navigation, not results:** GET navigates to the URL. It produces no `data` or `errors`.
- **Query string:** Submitted fields replace any query already in `action`.

## Methods and files

Each method calls the route export of the same name. This form updates a project with PUT:

**src/routes/projects/\[id\].tsx**

```tsx
import type { Handler } from "goribu/server";
import { Form } from "goribu";

// `project` comes from this route's GET handler.
export default function ProjectPage({ project }) {
  return (
    <Form method="put">
      {({ pending, errors }) => (
        <>
          <label htmlFor="name">Name</label>
          <input id="name" name="name" defaultValue={project.name} />
          <p>{errors?.name}</p>
          <button disabled={pending}>Save</button>
        </>
      )}
    </Form>
  );
}

export const PUT: Handler = async (req, res) => {
  const { name } = await req.body() as Record<string, unknown>;
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter a project name." });
  }

  // Save the new name for req.params.id here.
  return res.json({ saved: true });
};
```

**src/routes/projects/\[id\].jsx**

```jsx
import { Form } from "goribu";

// `project` comes from this route's GET handler.
export default function ProjectPage({ project }) {
  return (
    <Form method="put">
      {({ pending, errors }) => (
        <>
          <label htmlFor="name">Name</label>
          <input id="name" name="name" defaultValue={project.name} />
          <p>{errors?.name}</p>
          <button disabled={pending}>Save</button>
        </>
      )}
    </Form>
  );
}

export const PUT = async (req, res) => {
  const { name } = await req.body();
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter a project name." });
  }

  // Save the new name for req.params.id here.
  return res.json({ saved: true });
};
```

- **Methods:** `get`, `post`, `put`, `patch`, and `delete`, in any case. Each calls the route's export of the same name with the real HTTP method. There is no POST override.
- **Encoding:** Goribu picks it, switching to multipart when the form has a file input. Don't set `encType`.
- **Body shape:** `await req.body()` returns an object of fields whatever the encoding.
- **Files:** An upload is a `File` under its input's name, such as `body.avatar`.
- **Repeated names:** Become arrays in submission order. Unchecked or missing fields are absent.
- **Validation:** Check every value, and file size and type, on the server. See [Reading the body](/docs/handlers#reading-the-body).

## Pending state and completion

Use `reset` to clear the fields after success. This component assumes the displayed page has a POST handler:

**src/components/message-form.tsx**

```tsx
import { Form } from "goribu";

// Render this inside a page with a matching POST handler.
export default function MessageForm() {
  return (
    <Form method="post" reset>
      {({ pending, errors }) => (
        <>
          <label htmlFor="message">Message</label>
          <input id="message" name="message" />
          <p>{errors?.message}</p>
          <button disabled={pending}>Send</button>
        </>
      )}
    </Form>
  );
}
```

**src/components/message-form.jsx**

```jsx
import { Form } from "goribu";

// Render this inside a page with a matching POST handler.
export default function MessageForm() {
  return (
    <Form method="post" reset>
      {({ pending, errors }) => (
        <>
          <label htmlFor="message">Message</label>
          <input id="message" name="message" />
          <p>{errors?.message}</p>
          <button disabled={pending}>Send</button>
        </>
      )}
    </Form>
  );
}
```

- **Render props:** Children can be a function receiving `{ pending, errors, data }`.
- **Pending:** `true` while the request runs. Further submits from the same form are ignored automatically and old errors clear.
- **Reset:** Clears fields after `res.json` or `res.render`, not after errors or redirects.
- **Callbacks:** `onSubmit` can cancel with `preventDefault()`. `onResult` runs after the result is shown and before any redirect; check `result.ok`.
- **Ref:** A `ref` points to the `<form>` element.
- **Cancellation:** Unmounting the form or navigating away discards the pending result.

---

# Errors

Source: https://goribu.dev/docs/errors

When something goes wrong, Goribu shows visitors a friendly page and keeps the details for you.

## Expected and unexpected failures

Goribu treats errors in two ways:

- **Expected failures** are normal responses you return yourself: `res.invalid()` for form errors, `res.notFound()` for a missing resource, or a status with JSON for an API.
- **Unexpected errors** are anything thrown from a handler, middleware, metadata, or rendering. Goribu catches them, shows details in development, and shows your 500 page with an error ID in production.

Mistakes in routes or configuration don't reach visitors at all. They fail the build or dev server startup.

An API returns its expected error directly:

**src/routes/api/greet.ts**

```ts
import type { Handler } from "goribu/server";

export const POST: Handler = async (req, res) => {
  const { name } = await req.body() as Record<string, unknown>;
  if (typeof name !== "string" || !name.trim()) {
    return res.status(400).json({ error: "A name is required." });
  }
  return res.json({ name: name.trim() });
};
```

**src/routes/api/greet.js**

```js
export const POST = async (req, res) => {
  const { name } = await req.body();
  if (typeof name !== "string" || !name.trim()) {
    return res.status(400).json({ error: "A name is required." });
  }
  return res.json({ name: name.trim() });
};
```

## A 404 page

Add a custom page for unmatched URLs and `res.notFound()` responses:

**src/routes/\_404.tsx**

```tsx
import { Link } from "goribu";

export const meta = { title: "Page not found", robots: "noindex" };

// Help the visitor recover from a missing URL.
export default function NotFoundPage() {
  return (
    <main>
      <h1>Page not found</h1>
      <p>The page may have moved or no longer exists.</p>
      <Link href="/">Go home</Link>
    </main>
  );
}
```

**src/routes/\_404.jsx**

```jsx
import { Link } from "goribu";

export const meta = { title: "Page not found", robots: "noindex" };

// Help the visitor recover from a missing URL.
export default function NotFoundPage() {
  return (
    <main>
      <h1>Page not found</h1>
      <p>The page may have moved or no longer exists.</p>
      <Link href="/">Go home</Link>
    </main>
  );
}
```

- **When it shows:** For unknown URLs and whenever a handler returns `res.notFound()`. Without `_404`, Goribu uses a built-in page.
- **Passing data:** `res.notFound(props)` passes props to the page. Metadata comes from `_404`'s own `meta`, not the calling route.
- **Static in production:** Since v0.9.3, the build renders `_404` once and serves it from Static Assets, so unknown URLs never invoke the Worker. See [Which requests run the Worker](/docs/deployment#which-requests-run-the-worker).
- **No request data:** That static copy is shared by every visitor, gets empty props and the URL `/404`, and has no `responseHeaders`. It is there to protect against repeated requests for irrelevant pages. `res.notFound(props)` and misses under a dynamic route still render on the Worker with the request.

Because props can be empty, a `meta` function must handle missing fields:

**src/routes/\_404.tsx**

```tsx
import type { Meta } from "goribu";

type Props = { post?: { title: string } };

export const meta: Meta<Props> = ({ props }) => ({
  title: props.post ? `${props.post.title} was removed` : "Page not found",
  robots: "noindex",
});
```

**src/routes/\_404.jsx**

```jsx
export const meta = ({ props }) => ({
  title: props.post ? `${props.post.title} was removed` : "Page not found",
  robots: "noindex",
});
```

The build stops with a message naming the fix when:

- **`_404` throws** while rendering without a request, including inside `Suspense`. Move request-specific content to a handler using `res.notFound(props)`.
- **Another `404.html` exists** in `public/` or from a static route named `404`. Customize `src/routes/_404.tsx` instead.
- **`public/.assetsignore` excludes `404.html`.**

## A 500 page

A production error page receives `url`, `errorId`, and when it's actually behind Cloudflare a `cfRay`:

**src/routes/\_500.tsx**

```tsx
import type { ServerErrorProps } from "goribu/server";

export const meta = { title: "Something went wrong", robots: "noindex" };

// Share the reference ID without exposing the underlying exception.
export default function ServerErrorPage({ url, errorId, cfRay }: ServerErrorProps) {
  return (
    <main>
      <h1>Something went wrong</h1>
      <p>We could not load {url}.</p>
      <p>Reference: <code>{errorId}</code></p>
      {cfRay && <p>Ray ID: <code>{cfRay}</code></p>}
    </main>
  );
}
```

**src/routes/\_500.jsx**

```jsx
export const meta = { title: "Something went wrong", robots: "noindex" };

// Share the reference ID without exposing the underlying exception.
export default function ServerErrorPage({ url, errorId, cfRay }) {
  return (
    <main>
      <h1>Something went wrong</h1>
      <p>We could not load {url}.</p>
      <p>Reference: <code>{errorId}</code></p>
      {cfRay && <p>Ray ID: <code>{cfRay}</code></p>}
    </main>
  );
}
```

- **`url`:** The pathname only, without the query string.
- **`errorId`:** Logged on the server next to the original error, so a visitor can quote it and you can find the cause.
- **`cfRay`:** Cloudflare's Ray ID for the request, also logged with the error. It's absent in local development, so render it conditionally.
- **Fallback:** If `_500` itself fails, Goribu returns plain text with the same IDs.
- **Keep it safe:** Never show the caught exception in the page.

## Debugging in development

- **Request errors:** Return a plain-text 500 with the message and stack trace.
- **Import errors:** Vite's overlay shows the original error and the importing module, including server-only imports reaching the browser. Fix it and the page reloads without restarting `pnpm dev`.
- **Malformed bodies:** Invalid JSON or multipart data returns a safe 400, in development and production alike.

## Debugging in production

Every unhandled error is logged with its error ID and Ray ID. There are two ways to find it:

- **Past errors:** Turn on [Workers Logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/) for your Worker in the Cloudflare dashboard, then search for the ID a visitor gives you. Check [Cloudflare's pricing](https://developers.cloudflare.com/observability/pricing/) (starting from Dec. 20206) for log volume and retention.
- **Live errors:** Stream logs while you reproduce the problem. This shows only requests from the moment it starts:

**Terminal**

```sh
pnpm exec goribu tail
```

Keep credentials and private request data out of your own log messages.

## Common repairs

| Message or symptom | What to check |
| --- | --- |
| Route has no page or HTTP handler | Move a helper outside the route directory, or add a supported export. |
| Conflicting route shapes | Remove or rename duplicate URLs, including differently named dynamic parameters. |
| Handler returned an invalid value | Return a `res.*` result instead of a plain object or Response. |
| `res.render()` needs a default export | Add the page or return JSON, text, or a redirect. |
| Body could not be parsed | Match the request's Content-Type and send valid JSON or multipart data. |
| D1 or KV binding is missing | Declare the resource in config and restart development or rebuild. |
| D1 statement was awaited without a terminal | Add `.get()`, `.all()`, `.value()`, or `.run()`. |
| Server-only module reached browser code | Import it only from a handler or middleware. |
| Migration history drifted | Restore applied files and add a new forward migration. |
| Forced prerender cannot complete | Remove the incompatible handler or middleware, or use Worker rendering. |

- **Read the whole message:** `[Goribu]` messages name the file or API and the fix. The CLI omits stack traces and adds a `Caused by:` line when there's an underlying reason.
- **Wrangler:** Run any suggested Wrangler command as `pnpm exec goribu wrangler <args>`.

---

# Database: D1

Source: https://goribu.dev/docs/d1

Add one line of config and Goribu spins up a SQL database locally and in production, with safe queries right inside your handlers.

## Set up D1

D1 is Cloudflare's managed SQLite database ([Cloudflare D1](https://www.cloudflare.com/products/d1/)). To use it, add a `database` entry to your existing config:

**goribu.config.js**

```js
import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-09-01",
  database: { type: "d1", name: "my-app-db" }, // Add this
});
```

- **Local database:** `pnpm dev` uses a local database that is never uploaded. Don't forget to restart the dev server after changing the config.
- **Production database:** Deployment creates the named database the first time and reuses it afterwards.
- **Tables:** Create tables with a [migration](#migrations) before querying them. The [tutorial](/docs/tutorial) walks through a complete example.

## Read rows

Write SQL with the `req.d1` tagged template in a handler or middleware. Interpolated values are sent as SQL parameters, never pasted into the SQL text, so request input cannot inject SQL:

**Inside a request handler**

```ts
type Post = { id: number; title: string };

const post = await req.d1<Post>`
  SELECT id, title FROM posts WHERE id = ${req.params.id}
`.get();

const posts = await req.d1<Post>`
  SELECT id, title FROM posts ORDER BY id DESC
`.all();
```

**Inside a request handler**

```js
const post = await req.d1`
  SELECT id, title FROM posts WHERE id = ${req.params.id}
`.get();

const posts = await req.d1`
  SELECT id, title FROM posts ORDER BY id DESC
`.all();
```

A query runs only when you call one of these methods. Awaiting the query without one throws an error so no need to worry about mistakes.

| Method | Result |
| --- | --- |
| `.get()` | First row or `null`. |
| `.all()` | Array of rows, possibly empty. |
| `.value()` | First column of the first row or `null`, for counts and single values. |
| `.run()` | `{ changes, lastRowId }`, for inserts, updates, and deletes. |

- **Values:** Pass strings, numbers, booleans (stored as 1 or 0), `null`, or binary data. Convert dates to strings and objects with `JSON.stringify()` first.
- **Lists:** An array expands to one parameter per item, so `IN (${ids})` works. See [empty lists](#lists).

## Write rows

Validate input, write with `.run()` and turn a constraint failure into a field error:

**Inside a request handler**

```ts
export const POST: Handler = async (req, res) => {
  const { title } = await req.body() as Record<string, unknown>;
  if (typeof title !== "string" || !title.trim()) {
    return res.invalid({ title: "Enter a title." });
  }

  try {
    const { lastRowId } = await req.d1`
      INSERT INTO posts (title) VALUES (${title.trim()})
    `.run();

    return res.redirect(`/posts/${lastRowId}`);
  } catch (error) {
    // posts.title has a UNIQUE constraint.
    if (error.constraint === "unique") {
      return res.invalid({ title: "A post with this title already exists." });
    }
    throw error;
  }
};
```

**Inside a request handler**

```js
export const POST = async (req, res) => {
  const { title } = await req.body();
  if (typeof title !== "string" || !title.trim()) {
    return res.invalid({ title: "Enter a title." });
  }

  try {
    const { lastRowId } = await req.d1`
      INSERT INTO posts (title) VALUES (${title.trim()})
    `.run();

    return res.redirect(`/posts/${lastRowId}`);
  } catch (error) {
    // posts.title has a UNIQUE constraint.
    if (error.constraint === "unique") {
      return res.invalid({ title: "A post with this title already exists." });
    }
    throw error;
  }
};
```

- **Constraint errors:** For a SQLite constraint failure, the error has `constraint` (`"unique"`, `"notNull"`, `"foreignKey"`, or `"check"`) and, when SQLite reports them, `table`, `columns`, or `constraintName`. Rethrow other errors so they reach your error page.

## Atomic batches

Use `req.d1.atomic()` when several writes must all succeed or all fail. Pass the queries without `.run()`:

**Inside a request handler**

```ts
await req.d1.atomic([
  req.d1`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`,
  req.d1`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`,
]);
```

**Inside a request handler**

```js
await req.d1.atomic([
  req.d1`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`,
  req.d1`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`,
]);
```

- **Result:** One entry per query, each with `rows`, `changes`, and `lastRowId`.
- **Limitation:** The whole batch is sent at once. You cannot read a result in JavaScript and decide the next query inside the same batch. You have to express the condition in SQL instead.

## Replication and freshness

New databases get read replicas around the world, so reads are fast for distant visitors. This is handled for you automatically and without having to repeat the same code in each new app. Replicas can lag slightly behind the primary database, so Goribu gives you ways to handle that for you:

| Query | When to use it |
| --- | --- |
| `req.d1` | The default. A visitor always sees their own earlier writes, even after a redirect. |
| `req.d1.fresh` | Decisions that need the latest data from everyone, such as permissions, balances, or quotas. |
| `req.d1.public` | Shared content where data a moment old is fine, such as a public post list. |

**Inside a request handler**

```ts
const account = await req.d1.fresh<Account>`
  SELECT id, balance FROM accounts WHERE id = ${accountId}
`.get();
```

**Inside a request handler**

```js
const account = await req.d1.fresh`
  SELECT id, balance FROM accounts WHERE id = ${accountId}
`.get();
```

- **How the default works:** Goribu remembers the visitor's position in the database in a cookie and makes their next requests read at least that recent data.
- **Public is not caching:** `req.d1.public` only chooses where the query reads from. It does not make the HTTP response cacheable.
- **Turning replication off:** Set `replication: false` in the `database` config. All three query styles then read the primary database and no cookie is set.
- **Existing databases:** Without a `replication` setting, deployment leaves an existing database's replication as it is. Set `true` or `false` to change it on the next deploy.

## Migrations

Migrations are numbered SQL files that change your schema the same way locally and in production. Create the next one:

**Terminal**

```sh
pnpm exec goribu migrate:new create posts
```

Fill in its SQL. Keep both markers and leave the down section empty when the change cannot be safely reversed.

**migrations/0001\_create-posts.sql**

```sql
-- migrate:up
CREATE TABLE posts (
  id INTEGER PRIMARY KEY,
  title TEXT NOT NULL UNIQUE
);

-- migrate:down
DROP TABLE posts;
```

Apply pending migrations to the local database and check what has run:

**Terminal**

```sh
pnpm exec goribu migrate
pnpm exec goribu migrate:status
```

- **Production:** When you deploy, Goribu applies pending migrations before uploading the Worker, automatically. Add `--remote` to `migrate` or `migrate:status` to act on production directly.
- **History is fixed:** Never edit, remove, or reorder a migration that has run. Goribu detects it and stops. Restore the original file and then fix things in a new migration.
- **Failures:** Each migration runs as one batch with its tracking record, so a failed migration changes nothing and can be retried. Separate files are separate batches.
- **Rollback:** `pnpm exec goribu migrate:down` runs the down SQL of the latest migration. Read it first as it may delete data. It mostly exists as a tool in dev and should not be used in production.
- **Seed data:** Put local test data in `migrations/seed.sql` and run `pnpm exec goribu migrate:seed` after `migrate`. It runs the file as-is each time, so write it to be rerun safely, for example with `INSERT OR IGNORE`. It never runs against production.

**migrations/seed.sql**

```sql
INSERT OR IGNORE INTO posts (id, title) VALUES
  (1, 'Hello Goribu'),
  (2, 'Second post');
```

- **Live apps:** Migrations and the Worker upload are separate steps, so old code briefly runs against the new schema. Add schema first, deploy code that uses it and remove old columns in a later release. See [Deploys](/docs/deployment#schema-changes).

## Inspect data

Run SQL from the terminal with `goribu d1`, passing the SQL as one quoted argument:

**Terminal**

```sh
pnpm exec goribu d1 "SELECT id, title FROM posts ORDER BY id DESC LIMIT 5"
pnpm exec goribu d1 --remote "SELECT count(*) FROM posts"
```

- **Local:** Uses the same database as `pnpm dev` and needs no Cloudflare login.
- **Production:** With `--remote`, a single `SELECT` runs directly. Anything else asks you to type the database name first, and is refused outright in CI, scripts, and coding agents.
- **Not recorded:** Changes made this way are not tracked. Use a migration for production data changes you need to repeat.

## Dynamic SQL

Most queries that vary can stay a tagged template, with every value still a parameter.

### Optional filters

Bind `null` to mean "no filter". `undefined` is rejected, so convert missing values with `?? null`:

**Inside a request handler**

```ts
const status = req.query.get("status") ?? null;

const posts = await req.d1<Post>`
  SELECT id, title FROM posts
  WHERE (${status} IS NULL OR status = ${status})
  ORDER BY created_at DESC
`.all();
```

**Inside a request handler**

```js
const status = req.query.get("status") ?? null;

const posts = await req.d1`
  SELECT id, title FROM posts
  WHERE (${status} IS NULL OR status = ${status})
  ORDER BY created_at DESC
`.all();
```

### Lists

An empty array is rejected, because `IN ()` is not valid SQL and Goribu will not guess whether you meant "nothing" or "everything". Decide before querying:

**Inside a request handler**

```ts
if (ids.length === 0) return res.json([]);

const posts = await req.d1<Post>`
  SELECT id, title FROM posts WHERE id IN (${ids})
`.all();
```

**Inside a request handler**

```js
if (ids.length === 0) return res.json([]);

const posts = await req.d1`
  SELECT id, title FROM posts WHERE id IN (${ids})
`.all();
```

### Ordering

Choose between fixed orders with `CASE`:

**Inside a request handler**

```ts
const sort = req.query.get("sort") === "title" ? "title" : "newest";

const posts = await req.d1<Post>`
  SELECT id, title FROM posts
  ORDER BY CASE WHEN ${sort} = 'title' THEN title END,
           created_at DESC
`.all();
```

**Inside a request handler**

```js
const sort = req.query.get("sort") === "title" ? "title" : "newest";

const posts = await req.d1`
  SELECT id, title FROM posts
  ORDER BY CASE WHEN ${sort} = 'title' THEN title END,
           created_at DESC
`.all();
```

### Building SQL text

When the SQL itself must change, build it from fragments your code wrote and pass it to `req.d1.unsafe(text, params)` with a `?` for each value. Never put request input in the SQL text. `unsafe()` does not make it safe.

**Inside a request handler**

```ts
import type { D1Value } from "goribu/server";

const conditions: string[] = [];
const params: D1Value[] = [];

if (status) {
  conditions.push("status = ?");
  params.push(status);
}

if (authorId) {
  conditions.push("author_id = ?");
  params.push(authorId);
}

const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";

const posts = await req.d1
  .unsafe<Post>(`SELECT id, title FROM posts ${where} LIMIT ?`, [...params, 20])
  .all();
```

**Inside a request handler**

```js
const conditions = [];
const params = [];

if (status) {
  conditions.push("status = ?");
  params.push(status);
}

if (authorId) {
  conditions.push("author_id = ?");
  params.push(authorId);
}

const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";

const posts = await req.d1
  .unsafe(`SELECT id, title FROM posts ${where} LIMIT ?`, [...params, 20])
  .all();
```

- **No nesting:** Tagged templates cannot be nested or joined together; use `unsafe()` for that.
- **Arrays:** `unsafe()` does not expand arrays. Write one `?` per item yourself.

## Text search and case

SQLite's `LIKE`, `lower()`, and `upper()` only handle case for ASCII letters, so comparison with strings like these:`'Ελλάδα' LIKE 'ελλάδα'` is false. For case- and accent-insensitive search in any language, store a normalized copy of the text and search it with input normalized the same way:

**Inside a request handler**

```ts
const normalize = (text: string) =>
  text.normalize("NFD").replace(/\p{M}/gu, "").toLocaleLowerCase();

// Write: keep search_text next to the original title.
await req.d1`
  INSERT INTO posts (title, search_text) VALUES (${title}, ${normalize(title)})
`.run();

// Read: escape LIKE wildcards in the visitor's input with "!".
const term = normalize(query).replace(/[!%_]/g, "!$&");

const posts = await req.d1<Post>`
  SELECT id, title FROM posts WHERE search_text LIKE ${`%${term}%`} ESCAPE '!'
`.all();
```

**Inside a request handler**

```js
const normalize = (text) =>
  text.normalize("NFD").replace(/\p{M}/gu, "").toLocaleLowerCase();

// Write: keep search_text next to the original title.
await req.d1`
  INSERT INTO posts (title, search_text) VALUES (${title}, ${normalize(title)})
`.run();

// Read: escape LIKE wildcards in the visitor's input with "!".
const term = normalize(query).replace(/[!%_]/g, "!$&");

const posts = await req.d1`
  SELECT id, title FROM posts WHERE search_text LIKE ${`%${term}%`} ESCAPE '!'
`.all();
```

## Raw access

For libraries that need Cloudflare's D1 API directly, such as a query builder:

- **`req.d1.session`:** The same session `req.d1` uses, so the library keeps the read-your-own-writes behavior. Prefer this.
- **`req.d1.fresh.session`:** A session that starts at the primary database.
- **`req.d1.binding`:** The plain Cloudflare binding, with no session handling.

---

# Database: Bring your own

Source: https://goribu.dev/docs/databases

Use D1 for the built-in workflow, or connect to a service through an API that runs on Workers.

## What Goribu configures

- **Built-in provisioning:** Goribu provisions one D1 database through `database: { type: "d1", name }`.
- **External databases:** Goribu has no configuration fields or automatic provisioning for PostgreSQL, MySQL, or Hyperdrive.

Hyperdrive integration is not available in the current Goribu configuration API. Do not add a made-up `hyperdrive` field or edit generated Wrangler files to work around it.

## Use a provider's HTTP API

A service with an HTTPS API can be called from a handler using `fetch`. Keep its credentials in server environment values. This example assumes your service accepts a bearer token and returns JSON:

**src/lib/catalog.server.ts**

```ts
export type CatalogEnv = {
  CATALOG_API_URL: string;
  CATALOG_API_TOKEN: string;
};

// Adapt this path and response handling to your provider's documented API.
export async function readProducts(env: CatalogEnv): Promise<unknown> {
  const response = await fetch(new URL("/products", env.CATALOG_API_URL), {
    headers: { Authorization: `Bearer ${env.CATALOG_API_TOKEN}` },
  });
  if (!response.ok) throw new Error("The catalog request failed.");
  return response.json();
}
```

**src/lib/catalog.server.js**

```js
// Adapt this path and response handling to your provider's documented API.
export async function readProducts(env) {
  const response = await fetch(new URL("/products", env.CATALOG_API_URL), {
    headers: { Authorization: `Bearer ${env.CATALOG_API_TOKEN}` },
  });
  if (!response.ok) throw new Error("The catalog request failed.");
  return response.json();
}
```

**src/routes/products.ts**

```ts
import type { Handler } from "goribu/server";
import { readProducts } from "../lib/catalog.server";
import type { CatalogEnv } from "../lib/catalog.server";

// Only return fields that this endpoint is allowed to expose.
export const GET: Handler<Record<string, unknown>, CatalogEnv> = async (req, res) => {
  const products = await readProducts(req.env);
  return res.json(products);
};
```

**src/routes/products.js**

```js
import { readProducts } from "../lib/catalog.server";

// Only return fields that this endpoint is allowed to expose.
export const GET = async (req, res) => {
  const products = await readProducts(req.env);
  return res.json(products);
};
```

- **Environment values:** Set `CATALOG_API_URL` and `CATALOG_API_TOKEN` in `.env` locally and `.env.production` for deployment.
- **Provider contract:** The provider controls its endpoint, authentication, validation, consistency, and errors. Adapt the helper to those rules.

## Using an SDK or query builder

- **Runtime support:** Check that a library supports Cloudflare Workers. A Node.js driver is not automatically compatible.
- **Service ownership:** Goribu does not create a connection pool or manage an external service's schema.
- **D1 integrations:** `req.d1.session` provides the request's session while preserving Goribu's default consistency behavior.
- **Raw D1 binding:** `req.d1.binding` exposes the raw binding when an integration specifically requires it. See [D1](/docs/d1#raw-access).

## Keep the boundary clear

Place private clients and credentials in server-only modules outside `src/routes/`. Import them from handlers, and send only the data needed by the page through `res.render()`.

Use your provider's migration and deployment tools for its database. Goribu's migration commands apply only to D1.

---

# KV store

Source: https://goribu.dev/docs/kv

Store cached or shared values when a briefly stale read is acceptable.

## Set up a namespace

Add KV to your existing config:

**goribu.config.js**

```js
import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-09-01",
  kv: { name: "my-app-kv" },
});
```

- **Managed binding:** Goribu creates the `KV` binding locally and creates or reuses the named production namespace on deployment.
- **Namespace names:** Use lowercase letters, digits, hyphens, or underscores. Start with a letter or digit and use at most 63 characters.
- **Binding changes:** Restart development after changing bindings.
- **Local isolation:** Local values stay separate from production.
- **Configuration ownership:** Do not add a second Wrangler declaration for the namespace.

## Read and write

This route returns a cached timestamp, creating it when missing:

**src/routes/snapshot.ts**

```ts
import type { Handler } from "goribu/server";

type Snapshot = { createdAt: string };

// Cache a public snapshot whose age does not affect correctness.
export const GET: Handler = async (req, res) => {
  let snapshot = await req.kv.get<Snapshot>("snapshot", { type: "json" });
  if (snapshot === null) {
    snapshot = { createdAt: new Date().toISOString() };
    await req.kv.put("snapshot", JSON.stringify(snapshot), {
      expirationTtl: 300,
    });
  }
  return res.json(snapshot);
};
```

**src/routes/snapshot.js**

```js
// Cache a public snapshot whose age does not affect correctness.
export const GET = async (req, res) => {
  let snapshot = await req.kv.get("snapshot", { type: "json" });
  if (snapshot === null) {
    snapshot = { createdAt: new Date().toISOString() };
    await req.kv.put("snapshot", JSON.stringify(snapshot), {
      expirationTtl: 300,
    });
  }
  return res.json(snapshot);
};
```

- **Default reads:** `get()` returns text or `null` by default.
- **JSON reads:** Pass `{ type: "json" }` to parse JSON.
- **JSON writes:** Objects need explicit `JSON.stringify()`; writes have no automatic encoding.

A successful write is an acknowledgement, not a guarantee that the next reader will see it. This example returns the value it already has instead of depending on an immediate reread.

## Operations

| Method | Options and result |
| --- | --- |
| `get(key, options?)` | Read text, JSON, an ArrayBuffer, or a stream. Missing keys return null. |
| `put(key, value, options?)` | Write a value with optional `expiration`, `expirationTtl`, and metadata. |
| `delete(key)` | Delete a key; cached values can remain visible temporarily. |
| `list(options?)` | List one page of keys using `prefix`, `limit`, and `cursor`. |

- **Read options:** `get()` accepts an object with `type`, `cacheTtl`, and `metadata`. The shorthand `get(key, "json")` is not supported.
- **Metadata reads:** `{ metadata: true }` returns the native value/metadata result. There is no separate `req.kv.getWithMetadata()` method.
- **Absolute expiration:** `expiration` is an epoch timestamp in seconds.
- **Relative expiration:** `expirationTtl` is a lifetime in seconds.
- **Write completion:** Await writes and deletes before reporting success.
- **Platform limits:** The native platform validates storage values and limits.

**Read a value with metadata**

```ts
type Snapshot = { createdAt: string };
type Metadata = { source: string };

// Inside a handler with KV configured.
const entry = await req.kv.get<Snapshot, Metadata>("snapshot", {
  type: "json",
  metadata: true,
});
// entry.value is null when the key is missing.
```

**Read a value with metadata**

```js
// Inside a handler with KV configured.
const entry = await req.kv.get("snapshot", {
  type: "json",
  metadata: true,
});
// entry.value is null when the key is missing.
```

## Pagination

- **List result:** `list()` returns `keys`, `list_complete`, and a cursor when more results are available.
- **Next page:** Keep the prefix and limit when requesting the next page. Stop only when `list_complete` is `true`.

**src/routes/cache-keys.ts**

```ts
import type { Handler } from "goribu/server";

// Return one page of public cache-key names.
export const GET: Handler = async (req, res) => {
  const cursor = req.query.get("cursor") || undefined;
  const page = await req.kv.list({ prefix: "public:", limit: 100, cursor });
  return res.json(page);
};
```

**src/routes/cache-keys.js**

```js
// Return one page of public cache-key names.
export const GET = async (req, res) => {
  const cursor = req.query.get("cursor") || undefined;
  const page = await req.kv.list({ prefix: "public:", limit: 100, cursor });
  return res.json(page);
};
```

- **Listing access:** Only expose key listings appropriate for your app's users.
- **Manual iteration:** Goribu does not automatically paginate or retry KV operations.

## Choose KV deliberately

- **Stale reads:** KV is eventually consistent, including cached misses. After a write, a reader may see an older value or `null`.
- **Deletion visibility:** A deleted value may remain visible temporarily.
- **Code deployments:** Deploying new code does not flush KV caches.

Use KV for public snapshots, cached content, and data with an acceptable freshness window. Use [D1](/docs/d1) for authoritative records, exact counters, or a flow that must reliably show a visitor their own changes.

## Missing bindings and failures

- **Missing binding:** Using KV without its declaration fails with a repair message. Add the config, then restart development or rebuild.
- **Storage failures:** Storage errors propagate through the normal request boundary unless your handler catches them.

For an optional cache, you can handle cache errors and still return the authoritative result. Do not report that a required write succeeded when it failed.

---

# Cache

Source: https://goribu.dev/docs/cache

Avoid repeating expensive reads and computation with a small JSON cache on Cloudflare.

**Available in Goribu 0.9.0.** This guide describes request-scoped JSON caching through `req.cache`.

## Read and cache

Read a value with `req.cache`, load it from its source on a miss, then cache the result. The D1 query below needs a configured database and an existing polls table; see [D1](/docs/d1) for setup.

**src/routes/polls.ts**

```ts
import type { Handler } from "goribu/server";

type Poll = { id: number; title: string };

export const GET: Handler = async (req, res) => {
  const key = "/polls/recent:v1";
  let polls = await req.cache.get<Poll[]>(key);
  if (polls === null) {
    polls = await req.d1<Poll>`SELECT id, title FROM polls ORDER BY id DESC LIMIT 20`.all();
    await req.cache.set(key, polls, { ttl: 300 });
  }
  return res.json({ polls });
};
```

**src/routes/polls.js**

```js
export const GET = async (req, res) => {
  const key = "/polls/recent:v1";
  let polls = await req.cache.get(key);
  if (polls === null) {
    polls = await req.d1`SELECT id, title FROM polls ORDER BY id DESC LIMIT 20`.all();
    await req.cache.set(key, polls, { ttl: 300 });
  }
  return res.json({ polls });
};
```

- **Availability:** `req.cache` is available in handlers and middleware without a binding or configuration.
- **Cache misses:** Check misses with `=== null`. Cached `false`, `0`, and empty strings are valid results.
- **Absent results:** Stored `null` cannot be distinguished from a miss. Use an object such as `{ found: false }` to cache an absent result.

## Operations

| Call | Behavior |
| --- | --- |
| `get(key)` | Returns parsed JSON, or `null` on a miss or cache failure. |
| `set(key, value, options?)` | Attempts to store JSON. The only option is `ttl`, in seconds, defaulting to 60. |
| `delete(...keys)` | Attempts to remove one or more entries in the current data center. |

- **Completion:** Await each cache operation. `set` and `delete` resolve to `undefined`.
- **TTL validation:** TTL must be a positive safe integer. Zero, fractions, negative values, and non-finite numbers are rejected; there is no permanent setting.
- **Retention:** Entries can be evicted before TTL expiry. A resolved write does not guarantee Cloudflare retained it.
- **JSON conversion:** Dates become strings, undefined object properties are omitted, and non-finite numbers become `null`.
- **Rejected values:** Circular values, BigInts, and top-level values producing no JSON, such as `undefined`, functions, or symbols, are rejected.

**Typed reads**

```ts
type Poll = { id: number; title: string };

const polls = await req.cache.get<Poll[]>("/polls/recent:v1");
// Poll[] | null. The type argument does not validate stored data.
```

**Typed reads**

```js
const polls = await req.cache.get("/polls/recent:v1");
// Poll[] | null. The type argument does not validate stored data.
```

- **Read type:** Without a type argument, cache reads return `unknown`.
- **Public type:** `GoribuCache` is available from `goribu/server`.

## Keys and scope

- **Key format:** Cache keys are valid Unicode strings starting with `/`, such as `/polls/42`. They need not identify a route.
- **Literal identity:** `/polls/../42`, `/42`, `/42#summary`, and `/42?full` remain distinct keys.
- **Cache scope:** Requests to the same origin share entries within a data center. Different schemes, hosts, or ports have separate entries.
- **HTTP independence:** Goribu uses a named cache separate from the default HTTP cache. Storing a value does not publish it at that URL or change response cache headers.
- **Personalized entries:** Users on the same origin share keys. Include the user or tenant identifier in personalized keys, and authorize the request before reading them.
- **Shape changes:** Use versioned keys when changing the stored JSON shape across deployments.

## Refresh after mutations

After a successful database mutation, delete the affected entries or replace a local entry with the updated value you already have:

**Refresh affected entries**

```ts
// After the database mutation succeeds:
await req.cache.delete("/polls/recent:v1", `/polls/${id}`);

// Or, when the mutation already returned the updated record:
await req.cache.set(`/polls/${poll.id}`, poll, { ttl: 300 });
```

**Refresh affected entries**

```js
// After the database mutation succeeds:
await req.cache.delete("/polls/recent:v1", `/polls/${id}`);

// Or, when the mutation already returned the updated record:
await req.cache.set(`/polls/${poll.id}`, poll, { ttl: 300 });
```

- **Mutation confirmation:** Keep the authoritative mutation result to confirm a successful write.
- **Concurrent fills:** Cache fills can race with writes or deletions. The cache does not coordinate requests or provide transactions.
- **Local invalidation:** A cache update affects only the data center executing the Worker; it does not invalidate another location's copy.
- **Freshness window:** Choose a TTL matching the staleness your app can tolerate. Neither `req.cache` nor [KV](/docs/kv) provides global strong consistency.

## Smart Placement

- **Placement benefit:** Smart Placement can improve cache reuse and refresh behavior for localized apps by concentrating more reads and mutations near the app's data.
- **Shared execution location:** Requests reaching the same execution location share its local cache and updates.
- **Placement limits:** Other locations depend on their own updates or TTL expiry. Placement does not guarantee every request reaches one location.
- **Placement configuration:** Use [Cloudflare's Worker placement settings](https://developers.cloudflare.com/workers/configuration/placement/).

## Background writes and failures

To return a response without waiting for a cache fill, register the write explicitly with `req.waitUntil`:

**Fill the cache in the background**

```ts
req.waitUntil(
  req.cache.set("/polls/recent:v1", polls, { ttl: 300 }),
);
```

**Fill the cache in the background**

```js
req.waitUntil(
  req.cache.set("/polls/recent:v1", polls, { ttl: 300 }),
);
```

- **Explicit background work:** Ordinary cache calls never schedule background work automatically.
- **Deletion timing:** Await a deletion when the handler should wait for the local attempt to complete.
- **Invalid arguments:** Invalid keys, values, or options reject with an actionable `[Goribu]` error.
- **Batch validation:** Every key in a deletion batch is validated before deletion starts.
- **Platform failures:** Platform failures and unreadable cached JSON produce a warning and become a miss or skipped write/delete. The handler can continue.
- **Missing Cache API:** Reads miss and writes/deletes do nothing in a runtime without the Cache API. Argument validation still runs.
- **Local storage tests:** Development runs in workerd with a local Cache API. Use that runtime for tests needing actual storage.

## Deployment support

| Deployment | Cache API behavior |
| --- | --- |
| Custom domain or route | Cloudflare documents support; Goribu's custom-domain fixture passed live checks. |
| `workers.dev` | Goribu's named cache passed live checks on the tested deployment, despite the no-op restriction in Cloudflare's R2 guide. |
| Dashboard editor and Playground previews | Cloudflare documents that cache operations have no impact. |
| Worker fronted by Cloudflare Access | Cloudflare documents the Cache API as unavailable. |

- **Observed deployments:** Live checks on October 2, 2026 confirmed hits, literal keys, origin isolation, deletion, and TTL behavior on one custom domain and its `workers.dev` origin.
- **Evidence limits:** Those checks do not establish support for every deployment, previews, or Access.
- **Documentation discrepancy:** The discrepancy with [Cloudflare's R2 guide](https://developers.cloudflare.com/r2/examples/cache-api/) has no established explanation.
- **Platform restrictions:** The [Cache API reference](https://developers.cloudflare.com/workers/runtime-apis/cache/) documents the preview and Access restrictions.
- **Hit verification:** Verify actual hits where caching matters. Unsupported deployments can accept writes without retaining them and return misses without throwing.
- **Insufficient signals:** A resolved `set` or an absence of warnings does not prove a hit.
- **Separate product:** Cloudflare's Workers Cache product does not establish support for the Cache API used here.

## Static pages

- **Build-time reads:** Explicitly prerendered GET handlers bypass cache reads and writes so the build reads source data.
- **Fixed output:** Generated HTML and navigation props keep the build-time snapshot. Cache expiry or deletion does not refresh them.
- **Static updates:** Rebuild and deploy to update static output. See [pre-rendered pages](/docs/routing#pre-rendered-pages).

---

# R2 files & uploads

Source: https://goribu.dev/docs/r2

Store public media and private files, upload from React forms, and issue signed download links.

**Available in Goribu 0.9.0.** Managed R2 includes bucket configuration, storage APIs, signed downloads, and browser uploads.

## Configure buckets

Declare a default bucket and, optionally, a second private bucket. Goribu creates or reuses them during deployment and supplies `R2` and `R2_PRIVATE` bindings.

**goribu.config.js**

```js
import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-09-01",
  r2: {
    name: "my-app-media",
    domain: "media.example.com",
    private: { name: "my-app-files" },
    // jurisdiction: "eu", // Optional; applies to both buckets.
  },
});
```

- **Public hostname:** `domain` makes the default bucket public through that hostname. Use a separate media hostname in an active Cloudflare zone in your account.
- **Hostname format:** Supply only the hostname, without a scheme, port, or path.
- **Domain activation:** Goribu connects the media hostname during deployment. DNS and certificate activation may take time.
- **Single private bucket:** For private storage only, omit `domain` and access the default bucket through `req.r2`.
- **Second bucket:** The optional `private` bucket requires a public default bucket.
- **Bucket names:** Names must be distinct, use 3–63 lowercase letters, digits, or hyphens, and start and end with a letter or digit.
- **Jurisdiction:** Omit `jurisdiction` for default storage or use `"eu"` for both buckets.

A single private bucket needs only a name:

**goribu.config.js**

```js
import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-09-01",
  r2: { name: "my-app-files" },
});
```

- **Configuration ownership:** Configure R2 only through `goribu.config.js`. Handwritten Wrangler R2 declarations are rejected.
- **Bucket limit:** Goribu supports at most two managed buckets.

## Upload from a form

Declare `uploads` on the receiving route, then use `FileUpload` inside `Form`. Protect the route with [middleware](/docs/handlers) that checks the user's authorization; it runs before upload starts and again when the form is submitted.

**src/routes/profile.tsx**

```tsx
import type { Handler, R2Upload, UploadPolicy } from "goribu/server";
import { Form, FileUpload } from "goribu";

export const uploads = {
  avatar: { accept: ["image/*"], maxBytes: 5_000_000 },
} satisfies Record<string, UploadPolicy>;

export const POST: Handler = async (req, res) => {
  // The exported policy makes avatar a verified upload, not a raw File.
  const { avatar } = await req.body() as { avatar?: R2Upload };
  if (!avatar) return res.invalid({ avatar: "Upload an image." });
  // Save avatar.key with the user's record here.
  return res.json({ url: avatar.url });
};

export default function Profile() {
  return (
    <Form<{ url?: string }> method="post">
      {({ pending, uploading, errors, data }) => <>
        <FileUpload name="avatar" />
        {errors?.avatar && <p>{errors.avatar}</p>}
        {errors?.root && <p>{errors.root}</p>}
        {uploading && <p>Your file is uploading.</p>}
        <button disabled={pending}>
          {pending ? "Saving…" : "Save"}
        </button>
        {data?.url && <img src={data.url} alt="Saved avatar" />}
      </>}
    </Form>
  );
}
```

**src/routes/profile.jsx**

```jsx
import { Form, FileUpload } from "goribu";

export const uploads = {
  avatar: { accept: ["image/*"], maxBytes: 5_000_000 },
};

export const POST = async (req, res) => {
  // The exported policy makes avatar a verified upload, not a raw File.
  const { avatar } = await req.body();
  if (!avatar) return res.invalid({ avatar: "Upload an image." });
  // Save avatar.key with the user's record here.
  return res.json({ url: avatar.url });
};

export default function Profile() {
  return (
    <Form method="post">
      {({ pending, uploading, errors, data }) => <>
        <FileUpload name="avatar" />
        {errors?.avatar && <p>{errors.avatar}</p>}
        {errors?.root && <p>{errors.root}</p>}
        {uploading && <p>Your file is uploading.</p>}
        <button disabled={pending}>
          {pending ? "Saving…" : "Save"}
        </button>
        {data?.url && <img src={data.url} alt="Saved avatar" />}
      </>}
    </Form>
  );
}
```

- **Immediate transfer:** Picking a file starts the transfer immediately.
- **Transfer path:** By default, bytes stream through the Worker into R2. `direct: true` sends them straight to R2 in production.
- **Form submission:** Save waits for unfinished transfers, then submits signed references alongside the other form fields. File bytes are not sent again.
- **Verified references:** `await req.body()` verifies each reference against the stored object and returns `{ key, name, type, size, url? }`.
- **Public URLs:** Verified files in the public default bucket include `url`.
- **Missing uploads:** Invalid, expired, or failed uploads leave the field absent. Return `res.invalid()` when the file is required.
- **Application records:** Save the verified object key with your application record.
- **Transfer state:** `uploading` reports active transfers. `pending` reports submission, including its wait for uploads.
- **Form encoding:** Managed pickers have no input name, so the form stays URL-encoded unless it also contains an ordinary named file input.
- **JavaScript requirement:** Managed upload controls require JavaScript. See [Forms](/docs/forms) for submission and reset behavior.

## Policies and verification

**Policies on the receiving route**

```ts
import type { UploadPolicy } from "goribu/server";

export const uploads = {
  avatar: {
    accept: ["image/jpeg", "image/png"],
    maxBytes: 5_000_000,
    key: ({ ext }) => "avatars/" + crypto.randomUUID() + ext,
  },
  document: {
    accept: ["application/pdf"],
    maxBytes: 20_000_000,
    private: true,
  },
} satisfies Record<string, UploadPolicy>;
```

**Policies on the receiving route**

```js
export const uploads = {
  avatar: {
    accept: ["image/jpeg", "image/png"],
    maxBytes: 5_000_000,
    key: ({ ext }) => "avatars/" + crypto.randomUUID() + ext,
  },
  document: {
    accept: ["application/pdf"],
    maxBytes: 20_000_000,
    private: true,
  },
};
```

- **Required policy:** Each upload field requires `accept` MIME types and `maxBytes`, a positive integer.
- **MIME wildcards:** Subtype wildcards such as `image/*` are allowed; `*/*` is not.
- **Size limits:** Worker uploads allow up to 100,000,000 bytes. Direct policies allow up to 5,000,000,000 bytes.
- **Private field selection:** `private: true` stores the field in the second bucket, `r2.private`, and requires that bucket.
- **Single-bucket privacy:** `private: true` does not make a field private on its own. With one bucket and no `domain`, every upload is already private; leave `private` out.
- **Custom object keys:** The optional synchronous `key` function receives `{ req, file, ext }` after middleware.
- **Default object keys:** Without a key function, Goribu uses `uploads/<uuid><ext>`.
- **No overwrites:** Always choose a fresh key. Uploads refuse to overwrite existing objects; a fixed avatar key makes the next upload fail.
- **Replacing a file:** Save the verified new key first, then explicitly delete the old object.
- **Receiving handler:** A route exporting upload policies must also export `POST`, `PUT`, or `PATCH`.
- **Server boundary:** Upload policies and their key function remain server-only.
- **Worker rendering:** An upload-policy route runs on the Worker. Forcing `prerender = true` fails the build.
- **Static upload pages:** A static page can post to a separate action route containing the policies and handler. Its picker has no policy-derived type filter or instant size check; the action still enforces both.
- **Expiry:** Transfer targets last 60 seconds. Upload references last one hour.
- **Reference scope:** References bind the route pattern, field, bucket, and upload identity. They do not bind a user ID or a particular dynamic parameter.
- **Application authorization:** Authorize access in your app, keep references and signed URLs private, and handle repeated submissions deliberately.
- **Content verification:** Browser MIME types do not prove a file's contents. Keep files needing moderation private.
- **Public caching:** Public uploads receive `Cache-Control: public, max-age=31536000, immutable`.
- **Media headers:** Add an `X-Content-Type-Options: nosniff` response header rule on the media domain.

## Custom upload UI

**Preview and drop target**

```tsx
<FileUpload name="avatar">
  {({ file, previewUrl, status, errorMessage, showPicker, dropProps }) => (
    <div {...dropProps}>
      {previewUrl && <img src={previewUrl} alt="Selected image" />}
      <button type="button" onClick={showPicker}>
        {file ? file.name : "Choose or drop an image"}
      </button>
      {status === "uploading" && <p>Uploading…</p>}
      {errorMessage && <p>{errorMessage}</p>}
    </div>
  )}
</FileUpload>
```

**Preview and drop target**

```jsx
<FileUpload name="avatar">
  {({ file, previewUrl, status, errorMessage, showPicker, dropProps }) => (
    <div {...dropProps}>
      {previewUrl && <img src={previewUrl} alt="Selected image" />}
      <button type="button" onClick={showPicker}>
        {file ? file.name : "Choose or drop an image"}
      </button>
      {status === "uploading" && <p>Uploading…</p>}
      {errorMessage && <p>{errorMessage}</p>}
    </div>
  )}
</FileUpload>
```

- **Picker props:** `FileUpload` takes `name` and an optional render child.
- **File count:** Each upload field holds one file. Use distinct names for multiple fields.
- **Render props:** The render child receives `file`, `previewUrl`, `status`, `errorMessage`, `showPicker`, and `dropProps`.
- **Status values:** Upload status is `idle`, `uploading`, `done`, or `error`.
- **Opening the picker:** Call `showPicker()` from a user gesture.
- **New selections:** Picking a new file cancels the previous upload attempt.
- **Reset and unmount:** Reset and unmount clear the reference, abort pending work, and revoke the image preview URL.
- **Stored objects:** Reset does not delete a file already stored in R2.
- **Abandoned uploads:** Goribu does not automatically clean up abandoned uploads. Configure an R2 lifecycle rule for an appropriate upload prefix if needed.

## Upload without a form

Use `upload()` in a custom drop, paste or file-selection handler. Its action must be a same-origin route declaring the named policy. Submit the returned ref to that action to obtain the verified file.

**Custom upload handler**

```ts
import { upload, UploadError } from "goribu";

async function saveImage(file: File, signal?: AbortSignal) {
  try {
    const ref = await upload(file, {
      action: "/profile/save",
      name: "avatar",
      signal,
    });
    return await fetch("/profile/save", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ avatar: ref }),
      signal,
    });
  } catch (error) {
    if (signal?.aborted) return;
    if (error instanceof UploadError) {
      // Display error.message in your UI.
    }
    throw error;
  }
}
```

**Custom upload handler**

```js
import { upload, UploadError } from "goribu";

async function saveImage(file, signal) {
  try {
    const ref = await upload(file, {
      action: "/profile/save",
      name: "avatar",
      signal,
    });
    return await fetch("/profile/save", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ avatar: ref }),
      signal,
    });
  } catch (error) {
    if (signal?.aborted) return;
    if (error instanceof UploadError) {
      // Display error.message in your UI.
    }
    throw error;
  }
}
```

- **Displayable errors:** `UploadError.message` is ready to display to the user.
- **Error codes:** `UploadError.code` is `type`, `size`, `forbidden`, `network`, `expired`, or `server`.
- **Cancellation:** Cancellation also reports `network`. Check the signal to suppress cancellation UI.
- **Retry:** There is no automatic retry. Call `upload()` again for a fresh target.

## Read, write and download

- **Request APIs:** Handlers and middleware receive `req.r2` and, when configured, `req.r2.private`.
- **Native methods:** Both buckets expose `head`, `get`, `put`, `delete`, `list`, `createMultipartUpload`, and synchronous `resumeMultipartUpload`. Options and results follow the Workers R2 API.
- **Content type on writes:** A `File` or `Blob` supplies its content type on put when you have not set one explicitly.

**Server-side storage and links**

```ts
// In an authorized handler, after checking access to the record:
await req.r2.put("exports/latest.csv", csvBlob);
const publicUrl = req.r2.url("exports/latest.csv");

const downloadUrl = await req.r2.private.signedUrl(document.key, {
  expiresIn: 900,
  download: "report.pdf",
});
```

**Server-side storage and links**

```js
// In an authorized handler, after checking access to the record:
await req.r2.put("exports/latest.csv", csvBlob);
const publicUrl = req.r2.url("exports/latest.csv");

const downloadUrl = await req.r2.private.signedUrl(document.key, {
  expiresIn: 900,
  download: "report.pdf",
});
```

- **Public URL helper:** `url(key)` requires the public bucket and encodes each path segment. Development uses a local public-file endpoint.
- **Signed URL helper:** `signedUrl(key, options?)` works on either bucket.
- **Signed lifetime:** Signed links default to 900 seconds and accept 1–604800 seconds.
- **Download disposition:** Omit `download` for inline delivery, or supply an attachment filename.

**Available in Goribu 0.9.1.** For images or other files whose bytes never change under the same key, pass `immutable: true` to reuse links and allow private browser caching until they expire:

**A cacheable signed link**

```ts
// Authorize this user first. Replacing the image must create a new object key.
const imageUrl = await req.r2.private.signedUrl(image.fileKey, {
  expiresIn: 604800,
  immutable: true,
});
```

**A cacheable signed link**

```js
// Authorize this user first. Replacing the image must create a new object key.
const imageUrl = await req.r2.private.signedUrl(image.fileKey, {
  expiresIn: 604800,
  immutable: true,
});
```

- **Immutable default:** `immutable` defaults to `false`.
- **Link reuse:** With `immutable: true`, the same key, bucket, and options produce identical URLs within windows of half the requested lifetime. Each newly issued link has at least half its lifetime left.
- **Rotation example:** A seven-day immutable lifetime rotates URLs about every 3.5 days.
- **Private browser cache:** Immutable responses allow private browser caching bounded by link expiry, not shared CDN caching.
- **Revocation limit:** Cached bytes cannot be revoked by logout, permission changes, deletion, or secret rotation. Keep the default when that is unsuitable.

To serve a private file at a stable app URL instead of a signed link, check access in a route and return its body with [`res.stream()`](/docs/handlers#streaming-bytes), available since 0.9.2.

- **Worker downloads:** Signed downloads use the Worker when R2 API keys are absent. Development always uses the Worker.
- **Presigned downloads:** With both keys in production, signed downloads use R2's S3 endpoint, including its EU endpoint for EU buckets.
- **Partial credentials:** A partial R2 key pair fails explicitly.
- **Worker download features:** Worker downloads support HEAD, single byte ranges, and conditional requests.
- **Download sandbox:** Worker downloads use `Content-Security-Policy: sandbox` and `X-Content-Type-Options: nosniff`, so uploaded HTML or SVG cannot run scripts as the app.
- **Browser verification:** Inline PDF viewing and attachment downloads were verified in Chrome 154 on macOS.
- **Link authorization:** Issue signed links at request time after checking access. Links cannot be baked into prerendered HTML.
- **Bearer access:** The Worker download endpoint under `/_goribu/` does not run your middleware. A signed link is a bearer token until it expires.
- **Secret rotation:** Rotating `GORIBU_SECRET` invalidates Worker download links and upload references. Presigned downloads use separate R2 credentials.

## Direct uploads

**A larger private upload**

```ts
import type { UploadPolicy } from "goribu/server";

export const uploads = {
  video: {
    accept: ["video/mp4"],
    maxBytes: 500_000_000,
    direct: true,
    private: true,
  },
} satisfies Record<string, UploadPolicy>;
```

**A larger private upload**

```js
export const uploads = {
  video: {
    accept: ["video/mp4"],
    maxBytes: 500_000_000,
    direct: true,
    private: true,
  },
};
```

- **Receiving route:** Add a direct-upload policy to a route with a receiving handler.
- **Direct transfer:** Production sends bytes straight from the browser to R2. Development still uses local Worker storage.
- **Object verification:** Both transfer paths verify the object when its reference is submitted and use conditional writes to prevent overwrites.
- **Required secrets:** Direct uploads need an R2 API token stored as Worker secrets `R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY`.
- **Missing-key plan:** Since 0.9.2, keys need not be set up before deployment. `pnpm check` lists missing keys.
- **Interactive setup:** When either key is missing, `pnpm run deploy` from a terminal creates the upload buckets and prints a link to the account's R2 API tokens page, with the buckets to scope a new Object Read & Write token to.
- **Hidden prompts:** Deployment asks for each missing key through Wrangler's hidden prompt before uploading the Worker.
- **Name-only inspection:** Goribu checks secret names, never values. Keys declared only in `.env.production` still lead to prompts.
- **Cancelled setup:** Cancelling a key prompt stops deploy before Worker upload. Run deploy again to be asked for what is still missing.
- **Non-interactive setup:** A deploy without a terminal, such as CI, stops before any change when keys need setup and asks you to deploy once from a terminal.
- **Later deployments:** Later deploys reuse stored R2 secrets.

Deploy manages a `goribu-uploads` CORS rule only on buckets with direct fields, preserving unrelated rules. It allows PUT with `content-type`, `cache-control`, `if-none-match` and `x-amz-meta-goribu-upload`.

- **Allowed origins:** Direct-upload origins come from the app's workers.dev address unless [`workersDev: false`](/docs/configuration#workers-dev-address), Worker custom domains, and exact-host routes.
- **Excluded origins:** Hostname wildcards are skipped with a warning. Preview URLs are excluded.
- **Route schemes:** Routes without a scheme allow both HTTP and HTTPS origins.
- **Origin updates:** There is no separate origins setting. Redeploy after adding or changing app domains or routes.
- **Account inspection:** Direct-upload inspection requires an account workers.dev subdomain unless `workersDev: false`.
- **Inspection permissions:** Inspection needs Workers Scripts Read, Zone Read, and Workers Routes Read for the zones it scans. A narrowly scoped token may need additional permissions.
- **Key validation limit:** A credentials-name check does not prove the keys work or can access the buckets.

## Development and deployment

- **Local storage:** Development needs no R2 keys and keeps local bucket data across restarts.
- **Local signing:** Goribu creates `.goribu/dev-secret` once. Root env files still load normally; an app-provided `GORIBU_SECRET` wins.
- **Production exclusion:** The generated dev secret is excluded from production output.

**Inspect, then deploy**

```sh
pnpm build
pnpm check
pnpm run deploy
```

- **Build validation:** Build validates upload policies without creating cloud resources.
- **Read-only check:** Check labels upload metadata with the last build time. Without a build, it skips only CORS and key checks.
- **Deployment setup:** Deploy builds fresh, creates missing buckets, connects the public domain, configures direct-upload CORS, and generates `GORIBU_SECRET` if missing.
- **Draft Worker:** A first deploy may create a draft Worker. A later failure leaves it for retry.
- **Provisioning permissions:** Provisioning needs the relevant R2 read/write permissions and Workers Scripts access. Domain attachment also needs Zone Read.
- **Resource preservation:** Goribu never deletes buckets or objects during provisioning or deployment.
- **Renamed storage:** Changing bucket names or jurisdiction does not migrate files.
- **Public-domain removal:** Removing the domain setting does not disconnect an existing public domain.
- **Private-bucket conflict:** Public access on a configured private bucket blocks deployment and prints a repair command to run through `pnpm exec goribu wrangler`.
- **Verification cleanup:** Failed upload verification can delete only an object with the matching signed upload identity whose size or type is wrong.
- **Explicit deletion:** Your app can delete files through the request API.
- **Storage costs:** Review costs and lifecycle rules for files left behind by abandoned forms.

---

# Configuration

Source: https://goribu.dev/docs/configuration

Keep deployment identity and supported resources in one Node-loadable config file.

## goribu.config.js

Default-export the result of `defineConfig()` from `goribu/server`:

**goribu.config.js**

```js
import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-09-01",
  database: { type: "d1", name: "my-app-db" },
  kv: { name: "my-app-kv" },
});
```

- **Optional resources:** D1 and KV declarations are optional.
- **Node-loadable config:** Keep `goribu.config.js` plain JavaScript, including in TypeScript apps. Node loads it directly; do not import JSX, a Document, or application components.

## Options and defaults

| Option | Meaning and default |
| --- | --- |
| `name` | Required Worker name. Lowercase letters, digits, and hyphens; no leading or trailing hyphen; at most 63 characters. |
| `domain` | Optional application hostname connected during deployment. Omitted means no domain management. [Available since 0.9.0.](/docs/configuration#custom-domain) |
| `workersDev` | Optional boolean. `false` turns off the `workers.dev` address and requires `domain`. Defaults to `true`. [Available since 0.9.2.](/docs/configuration#workers-dev-address) |
| `compatibilityDate` | Required real date in `YYYY-MM-DD` format. |
| `compatibilityFlags` | Optional array of Workers compatibility flags. Defaults to an empty array. |
| `database` | Optional single D1 declaration. Omitted means no D1 binding. |
| `kv` | Optional single KV namespace. Omitted means no KV binding. |
| `responseHeaders` | Optional synchronous callback for Worker response defaults. |

- **Unknown fields:** Goribu rejects unknown configuration fields.
- **Generated configuration:** Edit `goribu.config.js` rather than generated `goribu.wrangler.jsonc` or production output.

## Custom domain

**Available in Goribu 0.9.0.** The top-level `domain` option connects an application hostname during deployment.

Add one line to connect your application to a custom hostname:

**goribu.config.js**

```js
import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-10-02",
  domain: "app.example.com",
});
```

- **Hostname format:** Use one bare hostname: a zone apex such as `example.com` or subdomain such as `app.example.com`. Goribu normalizes it to lowercase.
- **Rejected hostnames:** Schemes, paths, ports, IP addresses, wildcards, and Cloudflare-managed `workers.dev` or `r2.dev` addresses are rejected.
- **Zone ownership:** The hostname must belong to an active Cloudflare zone in the deployment account. Goribu finds the zone automatically.
- **Browser login:** Normal `goribu cloudflare-login` works for custom domains. No separate DNS Read permission is required.
- **API tokens:** Include Workers Scripts Write and Zone Read for the target zone alongside the app's other deployment permissions.
- **Connection preview:** `pnpm check` previews a domain connection without changing resources.
- **Attachment order:** `pnpm run deploy` checks ownership before provisioning, uploads the Worker, then checks again and attaches the hostname. For a new Worker, the domain conflict preview runs after its first upload.
- **Existing assignments:** A connection to this Worker is reused. Conflicting assignments block the operation; Cloudflare's replacement overrides remain disabled.
- **Activation:** Cloudflare creates DNS records and a TLS certificate. Activation may still be pending after attachment.
- **Attachment failure:** If connection fails after upload, the Worker remains deployed and the command reports an error. Resolve the problem and retry deployment.
- **Other addresses:** The `workers.dev` address remains available unless you [turn it off](#workers-dev-address). Other attached domains also remain available.
- **Old hostnames:** Changing or removing `domain` never disconnects an old hostname. Other attachments are listed as information.
- **Alias management:** Manage aliases such as `www`, redirects, and unwanted connections separately in Cloudflare.
- **Media hostname:** Use a different hostname for [`r2.domain`](/docs/r2#configure-buckets), which serves bucket files.
- **Upload CORS:** The planned application origin is included in R2 direct-upload CORS before domain attachment.
- **Local validation:** Development and standalone builds validate the hostname without contacting Cloudflare.

## workers.dev address

**Available in Goribu 0.9.2.** Every app is also served at `https://<name>.<account-subdomain>.workers.dev`. Once the app has its own domain, that second address may be unwanted: OAuth callbacks, cookies, and CORS are tied to one host. Turn it off with `workersDev: false`:

**goribu.config.js**

```js
import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-10-02",
  domain: "app.example.com",
  workersDev: false,
});
```

- **Required domain:** `workersDev: false` requires `domain`; otherwise the app would have no address.
- **Setting ownership:** Each deploy applies `workersDev`. Remove the field to restore workers.dev rather than changing the dashboard setting.
- **Activation timing:** Keep the default until the custom domain is connected and serving. DNS and TLS may need a few minutes; workers.dev works immediately.
- **Upload origin:** R2 direct-upload CORS drops the workers.dev origin when that address is disabled.
- **Preview URLs:** Deploys always turn off Cloudflare's per-version preview URLs. Goribu deploys production only; previews would be additional public app addresses.
- **One-time warning:** The first deploy disabling preview URLs on an existing Worker may print a Wrangler warning. No action is needed.

## Resources

- **D1 fields:** A D1 declaration accepts `type: "d1"`, `name`, and optional `replication`.
- **KV fields:** A KV declaration accepts only `name`.
- **Resource names:** D1 and KV names may contain lowercase letters, digits, hyphens, and underscores. Start with a letter or digit and use at most 63 characters.

Goribu owns the `DB` and `KV` bindings. You do not supply resource IDs or duplicate them in a Wrangler file.

- **Replication default:** Omitted replication enables it on new D1 databases and leaves existing settings untouched.
- **Replication reconciliation:** Explicit `true` or `false` reconciles replication during deployment. See [D1](/docs/d1#replication-and-freshness) and [KV](/docs/kv).
- **Resource selection:** Changing a resource name selects a different resource. It does not rename or delete the previous resource.
- **Declaration removal:** Removing a declaration leaves the production resource intact.

## Environment variables

Use `.env` for local values and `.env.local` for local overrides:

**.env**

```dotenv
CATALOG_API_TOKEN=local-placeholder
PUBLIC_API_ORIGIN=https://api.example.com
```

- **Server values:** Read server values through `req.env` in handlers or middleware.
- **Browser values:** Only `PUBLIC_*` variables are available to browser code through `import.meta.env`. Values are embedded at build time and must not contain secrets.

**Server code**

```ts
import type { Handler } from "goribu/server";

type Env = { CATALOG_API_TOKEN: string };

// Keep this value on the server; never return it in page props.
export const GET: Handler<Record<string, unknown>, Env> = (req, res) => {
  const token = req.env.CATALOG_API_TOKEN;
  return res.json({ configured: Boolean(token) });
};
```

**Server code**

```js
// Keep this value on the server; never return it in page props.
export const GET = (req, res) => {
  const token = req.env.CATALOG_API_TOKEN;
  return res.json({ configured: Boolean(token) });
};
```

**Browser code**

```ts
// In browser-reachable application code; this value is public.
const apiOrigin = import.meta.env.PUBLIC_API_ORIGIN;
```

**Browser code**

```js
// In browser-reachable application code; this value is public.
const apiOrigin = import.meta.env.PUBLIC_API_ORIGIN;
```

- **Worker-specific file:** Cloudflare supports `.dev.vars` for local Worker bindings.
- **File precedence:** If `.dev.vars` exists, even empty, it replaces loading of both `.env` and `.env.local` for the server. Choose one workflow; these files do not merge.
- **Local secrets exclusion:** Build output never contains local server values.
- **Build log wording:** Cloudflare's Vite plugin still prints "Using secrets defined in .env" during a build. Since 0.9.2, Goribu removes that local copy before output is written, so nothing local is uploaded.
- **Server build constants:** `import.meta.env.DEV`, `PROD`, and `MODE` work in handlers and server modules.
- **Development guards:** Vite replaces these values with constants. Production builds drop code that runs only when `DEV` is true; use this for development-only routes:

**src/routes/dev-login.ts**

```ts
import type { Handler } from "goribu/server";

// src/routes/dev-login.ts
export const POST: Handler = async (req, res) => {
  if (import.meta.env.DEV) {
    req.cookies.set("session", await createDevSession(req), { path: "/", httpOnly: true });
    return res.redirect("/");
  }
  return res.notFound();
};
```

**src/routes/dev-login.js**

```js
// src/routes/dev-login.js
export const POST = async (req, res) => {
  if (import.meta.env.DEV) {
    req.cookies.set("session", await createDevSession(req), { path: "/", httpOnly: true });
    return res.redirect("/");
  }
  return res.notFound();
};
```

- **Browser mode files:** Browser values follow Vite's `.env`, `.env.local`, `.env.development`, `.env.production`, and mode-specific local overrides.
- **Server mode distinction:** A value in `.env.development` does not become a server binding just because Vite can see it.

## Production secrets

- **Production source:** Put production values in `.env.production`. Deployment validates it with Wrangler and uploads its keys as Worker secrets.
- **Existing secrets:** Existing secrets omitted from `.env.production` remain on the Worker.
- **Missing file:** Without `.env.production`, Goribu uses existing platform secrets. Local `.env` is never an upload fallback.
- **Public prefix:** A `PUBLIC_*` value stays public even when the same key is uploaded as a Worker secret.
- **Shared placeholders:** Keep real environment files out of Git. Share placeholder names in `.env.example`.

Config evaluation does not load dotenv files into `process.env`. If the config reads an environment variable, supply it in the shell running the command.

## Response headers

Use a callback for defaults on Worker-served responses:

**goribu.config.js**

```js
import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-09-01",
  // Return ordinary header values synchronously.
  responseHeaders({ request, env, mode, nonce }) {
    return { "X-Content-Type-Options": "nosniff" };
  },
});
```

- **Callback arguments:** `responseHeaders` receives the original Request, Worker environment, development/production mode, and request nonce.
- **Return contract:** Return a plain object of strings or arrays of strings synchronously.
- **Header precedence:** Route and framework headers take precedence over callback defaults. `Vary` tokens merge.
- **Worker-rendered static pages:** A static page rendered by the Worker, in development or after a pre-render fallback, receives these headers and keeps its nonce. Prerendered HTML has neither.
- **Disallowed defaults:** Body, redirect, cookie, and transport headers cannot be blanket defaults: `Content-Type`, `Content-Length`, `Content-Range`, `Content-Encoding`, `Location`, `Set-Cookie`, `Trailer`, and `Transfer-Encoding`.
- **Response ownership:** Set those headers through the API that owns the response.
- **Static Assets:** `responseHeaders` does not run for Static Assets. App-authored `public/_headers` is rejected, so this API cannot establish a custom static-page header policy.
- **Security policy defaults:** Goribu does not set a default CSP or CORS policy.

## Development and build settings

- **Vite configuration:** Put Vite options in `vite.config.js`, not the Goribu app config. Keep `goribu()` in the plugins list.
- **CSS tooling:** Tailwind is an app plugin. Ordinary CSS works too.
- **Config reloads:** Changes to `goribu.config.js` or `vite.config.js` restart the development session.
- **Invalid replacements:** Invalid replacement config is reported while the existing session continues. Fix it before relying on new settings.
- **Undiscovered routes:** Restart `pnpm dev` if a newly added route is not recognized.

## Import aliases

Add import aliases through Vite's [`resolve.alias`](https://vite.dev/config/shared-options.html#resolve-alias) option in `vite.config.js`. This example maps `@` to your `src` directory using an absolute path. Merge it into your existing config, keeping any other plugins and settings:

**vite.config.js**

```js
import { fileURLToPath } from "node:url";
import { goribu } from "goribu/vite";

export default {
  plugins: [goribu()],
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
};
```

- **Alias usage:** Application code can use `import Button from "@/components/button"` for `src/components/button.tsx`.
- **Alias scope:** Vite aliases apply during development and production builds.
- **Config imports:** Keep `goribu.config.js` imports Node-compatible. Node loads that file directly without Vite aliases.

---

# Deploys

Source: https://goribu.dev/docs/deployment

Review the target, then let Goribu build and publish your Worker and static assets.

## Cloudflare setup

Use a Cloudflare account and choose a Worker name in `goribu.config.js`. Deploying to an existing name updates that Worker, so use the name intended for this app.

Log in to Cloudflare from the app directory:

**Terminal**

```sh
pnpm exec goribu cloudflare-login
```

- **Login command:** `goribu cloudflare-login` takes no arguments and needs no app configuration or build.
- **Login flow:** Goribu's installed Wrangler opens browser authorization and stores credentials for later runs.
- **Installed Wrangler:** Wrangler is a Goribu dependency, so a bare `wrangler` command is usually not on the app's PATH.
- **Wrangler wrapper:** Since 0.9.2, use `pnpm exec goribu wrangler <args>` for other Wrangler commands. It uses the account deploy would use; check and deploy repair messages use this form.
- **Deploy restriction:** `goribu wrangler deploy` is refused because it skips Goribu's build, provisioning, and migrations. `--dry-run` is allowed.
- **API token:** Supply `CLOUDFLARE_API_TOKEN` for non-interactive environments.
- **Account selection:** Set `CLOUDFLARE_ACCOUNT_ID` when credentials can reach multiple accounts.
- **Resource permissions:** Permissions must cover the Worker and any declared D1 or KV resources.
- **Authentication preflight:** Deploy validates credentials and account selection before building. It does not start login automatically.
- **Authentication repair:** Run `pnpm exec goribu cloudflare-login` locally or repair the token configuration, then retry.
- **Local commands:** Development and `pnpm build` need no Cloudflare authentication.
- **Account upgrade check:** When upgrading to 0.9.0, confirm the authenticated account before redeploying. Goribu passes it explicitly to Wrangler for secret validation and Worker upload, even when the app's `.env` names a different `CLOUDFLARE_ACCOUNT_ID`.
- **Explicit account override:** Set `CLOUDFLARE_ACCOUNT_ID` in the shell to select another authorized account.

## Preflight checks

**Terminal**

```sh
pnpm typecheck
pnpm build
pnpm check
```

**Terminal**

```sh
pnpm build
pnpm check
```

- **TypeScript check:** Skip `pnpm typecheck` in JavaScript apps.
- **Build:** `pnpm build` compiles the application and reports static output.
- **Deployment plan:** `pnpm check` reads the production plan without modifying resources.
- **Plan contents:** The plan includes the Worker name, resource names and bindings, creation or reuse, migration status, and intended production-secrets source.
- **Secret values:** The plan does not print secret values.

A bare app with no resources may not need Cloudflare access for check; a successful check is not proof of deploy permissions. Deployment performs its own authentication preflight.

## Deploy

**Terminal**

```sh
pnpm run deploy
```

- **Script invocation:** Use `pnpm run deploy`. Bare `pnpm deploy` is a different pnpm command.
- **Arguments:** Goribu's deploy takes no extra arguments.
- **Deployment sequence:** Deploy builds again, provisions declared resources, applies pending D1 migrations, and uploads the Worker and static assets.
- **Public URL:** Wrangler prints the public URL.
- **Production scope:** Deploy changes production; it is not a preview command.

Run the same command for later releases. Verify the deployed URL, the important forms, and any new database behavior after publishing.

- **Custom domains:** Available in Goribu 0.9.0. An optional [`domain` in configuration](/docs/configuration#custom-domain) connects an application hostname after Worker upload. Normal Wrangler login works.
- **Other addresses:** Custom-domain attachment preserves other domains and the `workers.dev` address unless [`workersDev: false`](/docs/configuration#workers-dev-address) is set.
- **Attachment failure:** If hostname attachment fails, the Worker remains deployed and the command reports the connection failure.

Since 0.9.2, deploys turn off Cloudflare's per-version preview URLs, which would only be extra public addresses for a production-only deploy. Existing Workers may show a one-time Wrangler warning about Preview URLs on the next deploy.

## Which requests run the Worker

- **Route-based execution:** Available in Goribu 0.9.3. A deployed app invokes the Worker only for URLs its routes can answer. There is nothing to configure.
- **Worker route rules:** Build sends each Worker route to the Worker, including `/subscribe` and `/subscribe/`, paths below a parameter such as `/posts/*`, and Goribu's navigation and R2 endpoints.
- **Other requests:** Static Assets answers all other requests. Probes such as `/wp-login.php` or `/.env` receive the app's [404 page](/docs/errors#a-404-page) without invoking the Worker.
- **Parameter scope:** A parameter covers everything below it. `/posts/42/wp-login.php` still reaches the Worker and receives the app's 404 page.
- **Narrow prefixes:** Put parameters below a static prefix to keep Worker exposure narrow.
- **Root parameters:** A root parameter such as `src/routes/[slug].tsx` can match any unknown URL. Those apps continue sending unknown URLs to the Worker; build prints a warning naming the route.
- **Routing limit:** Cloudflare allows 100 routing rules. Static files under a parameter, such as `public/posts/feed.xml` under `/posts/*`, each need an exclusion. Build fails rather than broadening routing past that limit.
- **Unknown methods:** In production, an unknown URL requested with a method other than GET or HEAD returns `405` from Static Assets.
- **Development routing:** Development sends every request to the Worker.

When upgrading to 0.9.3, run `pnpm build` before deploying. A build can now fail where it passed before; see [A 404 page](/docs/errors#a-404-page) for the 404-related causes.

## Live logs

**Available in Goribu 0.9.0.** Use `goribu tail` to inspect live Worker requests.

From the app directory, stream live logs from the deployed production Worker named in `goribu.config.js`. The command uses your Cloudflare login or shell API token without building or deploying:

**Terminal**

```sh
pnpm exec goribu tail
```

**Example output**

```text
GET https://app.example.com/hello - 200 OK @ 2026-10-02T10:30:00.000Z
GET https://app.example.com/missing - 404 Not Found @ 2026-10-02T10:30:01.000Z
GET https://app.example.com/boom - 500 Internal Server Error @ 2026-10-02T10:30:02.000Z
```

- **Request status:** Live log request lines show the actual HTTP response status, followed by console messages and exceptions.
- **Worker outcomes:** Worker failures appear separately, such as `[Worker outcome: exception]` when background work fails after a response.
- **Missing status:** If Cloudflare supplies no status, the line says `HTTP status unavailable`.
- **Traffic scope:** The stream includes all visitors and every hostname connected to the Worker.
- **Static requests:** Prerendered pages and files served by Static Assets do not appear because they do not invoke the Worker. Since 0.9.3, unknown URLs outside Worker routes are also absent.
- **Live-only events:** Tail shows live events, not historical logs.
- **Stop streaming:** Press Ctrl+C to close the stream and remote session. Shutdown errors remain visible.
- **Cleanup timeout:** If cleanup stalls for 10 seconds, Goribu stops locally and reports that any remaining remote session will expire automatically.
- **Piped output:** Piped log output remains JSON.
- **Tail arguments:** Tail takes no arguments or filters.

## Provisioning

After configuration, authentication, build, and any secrets-file validation succeed, Goribu prepares resources:

- Create the named D1 database if missing, or reuse the existing one.
- Apply an explicit D1 replication setting, leaving existing policy unchanged when omitted.
- Create or reuse the exact named KV namespace.
- Add the resolved IDs to generated production bindings.
- Verify D1 migration history and apply pending files before Worker upload.
- **Ambiguous resources:** Resource matching fails rather than choosing an ambiguous match.
- **Undeclared resources:** Undeclared resources are skipped. A KV-only app has no migration step.
- **Data preservation:** Deploying code does not erase D1 or KV data.
- **Resource selection:** Renaming a declaration selects another resource. Removing it does not delete the old resource.
- **Local isolation:** Local data is never copied to production automatically.

## Production secrets

- **Secret validation:** When `.env.production` exists, a Wrangler dry run validates it and the built Worker before provisioning or migrations.
- **Secret upload:** Deployment uploads that file's keys as Worker secrets and preserves other existing secrets.

Without the file, existing platform secrets remain in use. Local `.env` is not a fallback. Read [Configuration](/docs/configuration#production-secrets) for the distinction between server secrets and public browser values.

## Schema changes

Migrations run before the new Worker is uploaded, while the old Worker may still serve traffic. Keep the schema compatible with that old version.

Use an expand-and-contract sequence: add new tables or nullable columns first, deploy code that uses them, stop using the old shape in a later release, then remove it. Do not ship both an additive change and its destructive cleanup as simultaneously pending migrations.

- **Early migrations:** Use `pnpm exec goribu migrate --remote` for deliberate schema changes before deployment. Deploy still verifies history and applies any other pending migrations.
- **Migration requirement:** There is no `--no-migrations` flag.
- **Migration failure:** A failed migration stops the new Worker upload.
- **Partial progress:** Created resources and previously applied migration files can remain. The whole deployment is not a transaction. See [D1 migrations](/docs/d1#migrations).

## If deployment fails

Read the first error and repair that stage: configuration, authentication, build, secrets, provisioning, migration, or upload. A failed or interrupted command exits non-zero and does not report a successful deployment.

- **Output root:** Production output lives in `.goribu/dist/`.
- **Browser output:** `client/` contains HTML, browser assets, and static-navigation data.
- **Worker output:** The Worker environment subdirectory contains its bundle and deployment configuration.
- **Build report:** A successful `goribu build` prints discovered locations after pre-rendering completes. Public asset URLs stay the same.
- **Output ownership:** Goribu owns output paths and requires cleanup on every build. Remove conflicting output-directory overrides and `emptyOutDir: false` from Vite config or plugins.
- **Old output paths:** Update scripts and CI paths referencing root `dist/` when upgrading. Goribu leaves that old output untouched.
- **Environment discovery:** Keep `goribu.wrangler.jsonc` at the project root for environment-file discovery.

Keep generated `.goribu/`, `.wrangler/`, and `goribu.wrangler.jsonc` out of manual edits. They describe the build, not a second place to configure the app.

---

# Recipes

Source: https://goribu.dev/docs/recipes

Small patterns you can adapt without introducing another layer of application machinery.

## Search with a shareable URL

Let a GET form put the search term in the URL. The route handler reads it and returns page props:

**src/routes/search.tsx**

```tsx
import type { Handler } from "goribu/server";
import { Form } from "goribu";

type Props = { query: string; results: string[] };

// Filter sample data using the current query string.
export const GET: Handler<Props> = (req, res) => {
  const query = req.query.get("q")?.trim() ?? "";
  const items = ["React", "Cloudflare Workers", "D1", "KV"];
  const results = items.filter((item) => item.toLowerCase().includes(query.toLowerCase()));
  return res.render({ query, results });
};

// A GET form keeps the search usable through ordinary browser navigation.
export default function SearchPage({ query, results }: Props) {
  return (
    <main>
      <h1>Search</h1>
      <Form method="get" key={query}>
        <label>Search <input name="q" defaultValue={query} /></label>
        <button>Search</button>
      </Form>
      <ul>{results.map((item) => <li key={item}>{item}</li>)}</ul>
    </main>
  );
}
```

**src/routes/search.jsx**

```jsx
import { Form } from "goribu";

// Filter sample data using the current query string.
export const GET = (req, res) => {
  const query = req.query.get("q")?.trim() ?? "";
  const items = ["React", "Cloudflare Workers", "D1", "KV"];
  const results = items.filter((item) => item.toLowerCase().includes(query.toLowerCase()));
  return res.render({ query, results });
};

// A GET form keeps the search usable through ordinary browser navigation.
export default function SearchPage({ query, results }) {
  return (
    <main>
      <h1>Search</h1>
      <Form method="get" key={query}>
        <label>Search <input name="q" defaultValue={query} /></label>
        <button>Search</button>
      </Form>
      <ul>{results.map((item) => <li key={item}>{item}</li>)}</ul>
    </main>
  );
}
```

- **Input refresh:** The form key refreshes the uncontrolled input when the URL changes, including Back and Forward.
- **Stored search data:** Replace the sample list with a parameterized D1 query when search needs stored data.

## Set a preference cookie

Use a POST handler to validate a preference, set a cookie, and redirect. Read the cookie again in GET:

**src/routes/preferences.tsx**

```tsx
import type { Handler } from "goribu/server";
import { Form } from "goribu";

type Props = { density: "compact" | "comfortable" };

// Normalize the stored preference before passing it to the page.
export const GET: Handler<Props> = (req, res) => {
  const density = req.cookies.get("density") === "compact" ? "compact" : "comfortable";
  return res.render({ density });
};

// A redirect refreshes these props after the preference is saved.
export default function PreferencesPage({ density }: Props) {
  return (
    <Form method="post" key={density}>
      <label>
        Density
        <select name="density" defaultValue={density}>
          <option value="comfortable">Comfortable</option>
          <option value="compact">Compact</option>
        </select>
      </label>
      <button>Save</button>
    </Form>
  );
}

// Accept only the supported values, regardless of body encoding.
export const POST: Handler<Props> = async (req, res) => {
  const { density } = await req.body() as Record<string, unknown>;
  if (density !== "compact" && density !== "comfortable") {
    return res.invalid({ density: "Choose a supported density." });
  }
  req.cookies.set("density", density, {
    path: "/", maxAge: 2592000, httpOnly: true, sameSite: "Lax",
  });
  return res.redirect("/preferences");
};
```

**src/routes/preferences.jsx**

```jsx
import { Form } from "goribu";

// Normalize the stored preference before passing it to the page.
export const GET = (req, res) => {
  const density = req.cookies.get("density") === "compact" ? "compact" : "comfortable";
  return res.render({ density });
};

// A redirect refreshes these props after the preference is saved.
export default function PreferencesPage({ density }) {
  return (
    <Form method="post" key={density}>
      <label>
        Density
        <select name="density" defaultValue={density}>
          <option value="comfortable">Comfortable</option>
          <option value="compact">Compact</option>
        </select>
      </label>
      <button>Save</button>
    </Form>
  );
}

// Accept only the supported values, regardless of body encoding.
export const POST = async (req, res) => {
  const { density } = await req.body();
  if (density !== "compact" && density !== "comfortable") {
    return res.invalid({ density: "Choose a supported density." });
  }
  req.cookies.set("density", density, {
    path: "/", maxAge: 2592000, httpOnly: true, sameSite: "Lax",
  });
  return res.redirect("/preferences");
};
```

This stores a presentation preference, not an identity or authorization decision. Sensitive state needs server-side verification.

## Cache public data with KV

Read authoritative data from D1 and use KV only as an optional cache. This example assumes the tutorial's feedback table and both resources are configured:

**src/routes/public-feedback.ts**

```ts
import type { Handler } from "goribu/server";

type Message = { name: string; message: string };
type Snapshot = { messages: Message[]; cachedAt: string };

// Serve a snapshot where a short delay in visibility is acceptable.
export const GET: Handler = async (req, res) => {
  try {
    const cached = await req.kv.get<Snapshot>("public:feedback:v1", { type: "json" });
    if (cached !== null) return res.json(cached);
  } catch {
    console.warn("Feedback cache read failed; using D1.");
  }

  const messages = await req.d1.public<Message>`
    SELECT name, message FROM feedback ORDER BY id DESC LIMIT 10
  `.all();
  const snapshot = { messages, cachedAt: new Date().toISOString() };
  try {
    await req.kv.put("public:feedback:v1", JSON.stringify(snapshot), {
      expirationTtl: 300,
    });
  } catch {
    console.warn("Feedback cache write failed; returning the database result.");
  }
  return res.json(snapshot);
};
```

**src/routes/public-feedback.js**

```js
// Serve a snapshot where a short delay in visibility is acceptable.
export const GET = async (req, res) => {
  try {
    const cached = await req.kv.get("public:feedback:v1", { type: "json" });
    if (cached !== null) return res.json(cached);
  } catch {
    console.warn("Feedback cache read failed; using D1.");
  }

  const messages = await req.d1.public`
    SELECT name, message FROM feedback ORDER BY id DESC LIMIT 10
  `.all();
  const snapshot = { messages, cachedAt: new Date().toISOString() };
  try {
    await req.kv.put("public:feedback:v1", JSON.stringify(snapshot), {
      expirationTtl: 300,
    });
  } catch {
    console.warn("Feedback cache write failed; returning the database result.");
  }
  return res.json(snapshot);
};
```

- **Stale public data:** This endpoint deliberately allows stale public data. Keep the submitter's confirmation page on default D1 queries rather than reading it through KV.
- **Failure handling:** Catch only the optional cache failure. An authoritative database failure should still fail the request.

## Keep a page static and its action dynamic

A page with no handlers can remain static while its Form submits elsewhere:

**src/routes/check-name.tsx**

```tsx
import { Form } from "goribu";

type Result = { message: string };

// The initial page needs no request-specific props.
export default function CheckNamePage() {
  return (
    <Form<Result> method="post" action="/check-name-result">
      {({ pending, errors, data }) => (
        <>
          <label>Name <input name="name" /></label>
          <p>{errors?.name}</p>
          <button disabled={pending}>Check name</button>
          <p>{data?.message}</p>
        </>
      )}
    </Form>
  );
}
```

**src/routes/check-name.jsx**

```jsx
import { Form } from "goribu";

// The initial page needs no request-specific props.
export default function CheckNamePage() {
  return (
    <Form method="post" action="/check-name-result">
      {({ pending, errors, data }) => (
        <>
          <label>Name <input name="name" /></label>
          <p>{errors?.name}</p>
          <button disabled={pending}>Check name</button>
          <p>{data?.message}</p>
        </>
      )}
    </Form>
  );
}
```

**src/routes/check-name-result.ts**

```ts
import type { Handler } from "goribu/server";

// Return data to the existing form rather than rendering a different route.
export const POST: Handler = async (req, res) => {
  const { name } = await req.body() as Record<string, unknown>;
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter a name." });
  }
  return res.json({ message: `Hello, ${name.trim()}.` });
};
```

**src/routes/check-name-result.js**

```js
// Return data to the existing form rather than rendering a different route.
export const POST = async (req, res) => {
  const { name } = await req.body();
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter a name." });
  }
  return res.json({ message: `Hello, ${name.trim()}.` });
};
```

- **In-place results:** Return JSON from the separate action to update the existing form.
- **Other screens:** Return a redirect from the action to navigate to another screen.
- **Render restriction:** A separate action cannot use enhanced `res.render()` to replace a page at a different pathname.
- **Before hydration:** The example's native POST displays the returned JSON as a document.

## Add Google Analytics

Add the Google tag to your Document so it loads once on a direct visit and stays in place during client-side navigation. Merge the analytics code into your existing Document, keeping your fonts, theme script, and other shared tags. Replace `G-XXXXXXXXXX` with your GA4 web stream's measurement ID:

**src/setup/\_document.tsx**

```tsx
import { ClientEntry, Stylesheet } from "goribu";
import type { DocumentProps } from "goribu";

const measurementId = "G-XXXXXXXXXX";
const analyticsScript = `
  window.dataLayer = window.dataLayer || [];
  function gtag() { window.dataLayer.push(arguments); }
  gtag("js", new Date());
  gtag("config", ${JSON.stringify(measurementId)});
`;

// Load the Google tag once per document, outside the hydrated page root.
export default function Document({ children, head, nonce }: DocumentProps) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Stylesheet />
        {head}
        {import.meta.env.PROD && (
          <>
            <script
              async
              nonce={nonce}
              src={`https://www.googletagmanager.com/gtag/js?id=${measurementId}`}
            />
            <script nonce={nonce} dangerouslySetInnerHTML={{ __html: analyticsScript }} />
          </>
        )}
      </head>
      <body>
        <div id="root">{children}</div>
        <ClientEntry src="/src/setup/client-entry.js" nonce={nonce} />
      </body>
    </html>
  );
}
```

**src/setup/\_document.jsx**

```jsx
import { ClientEntry, Stylesheet } from "goribu";

const measurementId = "G-XXXXXXXXXX";
const analyticsScript = `
  window.dataLayer = window.dataLayer || [];
  function gtag() { window.dataLayer.push(arguments); }
  gtag("js", new Date());
  gtag("config", ${JSON.stringify(measurementId)});
`;

// Load the Google tag once per document, outside the hydrated page root.
export default function Document({ children, head, nonce }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Stylesheet />
        {head}
        {import.meta.env.PROD && (
          <>
            <script
              async
              nonce={nonce}
              src={`https://www.googletagmanager.com/gtag/js?id=${measurementId}`}
            />
            <script nonce={nonce} dangerouslySetInnerHTML={{ __html: analyticsScript }} />
          </>
        )}
      </head>
      <body>
        <div id="root">{children}</div>
        <ClientEntry src="/src/setup/client-entry.js" nonce={nonce} />
      </body>
    </html>
  );
}
```

- **Development exclusion:** `import.meta.env.PROD` leaves analytics out of `pnpm dev`.
- **Production inclusion:** Production builds include the analytics snippet on pre-rendered and Worker-rendered pages.
- **Public identifier:** The measurement ID is public. No server binding or secret is needed.
- **Navigation tracking:** Goribu changes browser history between pages. In the GA4 web stream, open **Enhanced measurement → Page views → Show advanced settings** and enable **Page changes based on browser history events** alongside page-load tracking.
- **Page-load-only behavior:** Without history-event tracking, this snippet covers only full page loads.
- **Duplicate events:** Keep the automatic setup as the single source of page views. Adding manual `page_view` events would double-count visits.
- **Analytics verification:** With debug mode enabled, verify a direct visit, a Link transition, and Back/Forward in Google's DebugView.
- **Expected event:** Each page change should produce one `page_view` with the expected URL, title, and referrer. See Google's [single-page application guide](https://developers.google.com/analytics/devguides/collection/ga4/single-page-applications) for setup and verification.

---

# Complete API reference

Source: https://goribu.dev/docs/api-reference

The public framework surface in one place. Follow the linked guides for examples and behavior in context.

## Package entry points

| Entry | Exports and purpose |
| --- | --- |
| `goribu` | `Link`, `NavLink`, `navigate`, `Form`, `Stylesheet`, `ClientEntry`, and UI/metadata types. |
| `goribu/server` | `defineConfig`, low-level `createApp`, and request, response, config, data, and middleware types. |
| `goribu/client` | Side-effect browser bootstrap. Import once from the client entry. |
| `goribu/vite` | `goribu()` Vite plugin for development and build integration. |

- **Runtime boundary:** Keep server runtime imports out of browser-reachable components.
- **Type-only imports:** Type-only imports do not create runtime dependencies.

## Route exports

| Export | Contract |
| --- | --- |
| `default` | React page component. Receives the props passed to `res.render()`. |
| `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS` | `(req, res) => ResponseResult`, optionally async. |
| `meta` | Metadata object or synchronous `({ props, url }) => metadata`. |
| `prerender` | Optional boolean. False requires Worker rendering; true requires successful static output. |

- **Implicit methods:** A page has an implicit GET when no explicit GET exists. Goribu derives HEAD and OPTIONS when needed.
- **Special routes:** `_404`, `_500`, and `_middleware` have special roles under routes.
- **Document location:** The optional app-wide Document lives in `src/setup/_document` with a supported JavaScript or TypeScript extension.
- **Middleware export:** A middleware default export is one function or an array. Return nothing to continue or a response result to stop.

## Request

Handlers and middleware share one request object.

| Member | Type or result |
| --- | --- |
| `method` | HTTP method string. |
| `path` | URL pathname string. |
| `url` | Absolute `URL` of the handled route; on client navigation, the target page's URL (available since 0.9.2). |
| `params` | Named dynamic segments, each a string. |
| `query` | `URLSearchParams`. |
| `headers` | `Headers`. |
| `env` | Worker environment and bindings. |
| `cookies` | Cookie jar described below. |
| `d1` | D1 query facade described below. |
| `kv` | KV facade described below. |
| `cache` | JSON cache described below (available since 0.9.0). |
| `body()` | Promise of an object or string, according to Content-Type. Both form encodings return objects. |
| `rawBody()` | Promise of Uint8Array bytes, sharing the cached read with body(). |
| `waitUntil(promise)` | Register background work with the Worker execution context. |

Middleware may attach its own fields to `req`, such as `req.user`, for later middleware and the handler; declare them for TypeScript on `AppRequestFields`. See [Request handlers](/docs/handlers#passing-data-to-the-route).

- **JSON bodies:** JSON bodies must have an object root.
- **Form bodies:** URL-encoded and multipart forms return field objects. Uploads are File values, repeated names become arrays, and missing fields are absent.
- **Text bodies:** Text returns a string.
- **Unsupported bodies:** Empty or unsupported bodies return an empty object.
- **Parse failures:** Malformed supported bodies produce 400. See [Request handlers](/docs/handlers#reading-the-body).

**src/routes/name.ts**

```ts
import type { Handler } from "goribu/server";

export const POST: Handler = async (req, res) => {
  const { name } = await req.body() as Record<string, unknown>;
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }
  return res.json({ name: name.trim() });
};
```

**src/routes/name.js**

```js
export const POST = async (req, res) => {
  const { name } = await req.body();
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }
  return res.json({ name: name.trim() });
};
```

## Response

Return one terminal result from every handler. `status()` and `headers()` configure the builder and return it for chaining.

| Method | Contract |
| --- | --- |
| `status(code)` | Set the HTTP status. Default is 200, except helper-specific defaults. |
| `headers(object)` | Add header strings or arrays of strings. |
| `render(props = {})` | Render this route's page with serializable object props. |
| `json(data)` | JSON response. |
| `text(body)` | Plain text response. |
| `stream(body)` | Bytes from a ReadableStream, ArrayBuffer, typed array, or Blob; `application/octet-stream` unless you set `content-type` (available since 0.9.2). |
| `invalid(errors, status = 422)` | Field-error object or string mapped to `root`. |
| `redirect(location)` | Redirect with default status 303. Explicit allowed statuses: 301, 302, 303, 307, 308. |
| `notFound(props = {})` | Render the 404 page with optional props. |

- **Return values:** Handlers cannot return raw Response objects or JSX. Use `stream()` for binary or streamed bodies.
- **Streamed routes:** A streamed route is never prerendered. Client navigation to it loads the document.
- **Bodyless statuses:** Bodyless statuses reject a body.
- **Form outcomes:** Enhanced Form outcomes are JSON, invalid, redirect, and same-page render. See [Forms](/docs/forms#choose-the-result).

## Cookies

| Method | Contract |
| --- | --- |
| `req.cookies.get(name)` | Incoming string value or null. |
| `req.cookies.set(name, value, options?)` | Queue a Set-Cookie header. |
| `req.cookies.delete(name, { path?, domain? }?)` | Queue deletion using matching scope. |

- **Cookie options:** `domain`, `path`, `expires` (Date), `maxAge` (seconds), `httpOnly`, `secure`, and `sameSite`.
- **SameSite values:** `sameSite` accepts `Lax`, `Strict`, or `None`, also lowercase.
- **Security defaults:** Cookie security options have no implicit defaults.
- **Cookie encoding:** Encode structured or Unicode data before setting a cookie.

## Navigation

| API | Extra props or arguments |
| --- | --- |
| `Link` | Normal anchor props, `replace = false`, `prefetch = true`. |
| `NavLink` | Link props plus `end = false` and a string or `({ isActive }) => className` callback. Goribu owns `aria-current`. |
| `navigate(target, { replace? }?)` | Returns Promise\<void\>. Requires a browser and an HTTP(S) destination. |

- **Active matching:** NavLink matches pathname boundaries, ignoring query and hash. Root is exact-only.
- **Native links:** Link enhancement preserves native behavior for external links, downloads, modifier clicks, and same-document anchors. See [Links & navigation](/docs/navigation).
- **Static navigation:** Production static navigation and prefetch reuse saved build-time data without invoking the Worker.
- **Current static URL:** Clicking the exact current URL scrolls a confirmed static page without fetching or rerendering.
- **Current dynamic URL:** Clicking the exact current URL of a dynamic page fetches fresh data.
- **Current-URL history:** Neither static nor dynamic navigation to the exact current URL adds a history entry.

**Exact active link**

```tsx
import { NavLink } from "goribu";

export default function SettingsLink() {
  return (
    <NavLink
      href="/settings"
      end
      className={({ isActive }) => isActive ? "active" : undefined}
    >
      Settings
    </NavLink>
  );
}
```

**Exact active link**

```jsx
import { NavLink } from "goribu";

export default function SettingsLink() {
  return (
    <NavLink
      href="/settings"
      end
      className={({ isActive }) => isActive ? "active" : undefined}
    >
      Settings
    </NavLink>
  );
}
```

## Form

Import `Form` from `goribu`. It accepts ordinary form props except that Goribu owns encoding and defines its method/action behavior.

| Prop | Contract |
| --- | --- |
| `method` | Required: get, post, put, patch, or delete, in upper or lower case. |
| `action` | Defaults to the current URL when submitted. |
| `children` | React children or `({ pending, errors, data }) => children`. |
| `replace` | Replace history during enhanced navigation; defaults false. |
| `reset` | Reset controls after successful JSON or same-page render; defaults false. |
| `onSubmit` | Runs first and may cancel with preventDefault(). |
| `onResult` | Runs after state/render commit and before redirect navigation. |
| `ref` | Receives the HTML form; extended-method forms expose it after hydration. |

- **Initial Form state:** `{ pending: false, errors: null, data: null }`.
- **Form errors:** `errors` is an object of message strings.
- **Result callback:** `onResult` receives `{ ok: true, data?, response? }` or `{ ok: false, errors, data?, response? }`.
- **Encoding ownership:** Do not pass `encType` to Form.
- **Hydration:** GET/POST work natively. PUT/PATCH/DELETE require hydration.
- **Submitter overrides:** A submitter's `formMethod` supports only GET/POST. Declare extended methods on Form itself. See [Forms](/docs/forms).

## Metadata

`meta` is a `RouteMetadata` object or synchronous function receiving `{ props, url }`, where url is a URL object.

| Field | Shape |
| --- | --- |
| `title` | String. Missing title produces an empty managed title. |
| `description`, `canonical`, `robots` | Strings. |
| `meta` | Array of `{ name, content }` or `{ property, content }`. |
| `links` | Array of descriptors with required `rel` and `href`. |

- **Optional link fields:** `as`, `type`, `media`, `sizes`, `hrefLang`, `crossOrigin`, `referrerPolicy`, `fetchPriority`, `imageSrcSet`, `imageSizes`, and `color` are all strings.
- **Rejected metadata:** Unknown fields, event handlers, async results, and duplicate canonical/description representations are rejected.

## Document and browser entry

`DocumentProps` contains `{ children, head, nonce? }`. Keep children under `#root` and head inside the document head.

- **Stylesheet:** `Stylesheet()` renders the current graph's styles and takes no public props.
- **Client entry:** `ClientEntry({ src, nonce? })` renders the browser entry. `src` is the development fallback; production resolves the built asset.
- **Custom Document:** Keep one `Stylesheet` and one `ClientEntry` in a custom Document.
- **Browser bootstrap:** Import `goribu/client` once to hydrate and install navigation and Forms.
- **Browser environment:** Only `import.meta.env.PUBLIC_*` values are browser-visible. See [Rendering](/docs/rendering).

## D1

Use the `req.d1` tagged template in handlers or middleware. Values become parameters. A statement is lazy until a terminal runs.

| API | Result or purpose |
| --- | --- |
| `.get()` | Promise of first row or null. |
| `.all()` | Promise of row array. |
| `.value()` | Promise of first column of first row or null. |
| `.run()` | Promise of `{ changes, lastRowId }`. |
| `req.d1.atomic(statements)` | Atomic batch of unexecuted statements; entries have rows, changes, and lastRowId. |
| `req.d1.unsafe(text, params?)` | Statement from application-controlled SQL structure and explicit values. |
| `req.d1.fresh` | Query facade that starts each tagged terminal at the primary. |
| `req.d1.public` | Query facade without the visitor's bookmark. |
| `.session` | Session object for integrations; raw binding when replication is disabled. |
| `.binding` | Plain Cloudflare D1Database binding. |

- **Tagged D1 values:** Strings, numbers, booleans, null, ArrayBuffer, ArrayBufferView, and non-empty arrays of those scalars are supported.
- **Unsafe parameters:** `unsafe()` parameters are a flat scalar array.
- **Rejected D1 values:** Undefined, dates, objects, nested/empty arrays, functions, symbols, and bigints are rejected.
- **Default consistency:** Default D1 queries use the visitor session when replication is enabled.
- **Facade restrictions:** Fresh/public cannot be chained. Atomic belongs to the default facade.
- **Batch session:** A batch rebinds passed statements to its own session. See [D1](/docs/d1).

**Typed row results**

```ts
// Inside a handler; D1 and the posts table must exist.
type Post = { id: number; title: string };

const posts = await req.d1<Post>`
  SELECT id, title FROM posts ORDER BY id DESC
`.all();
```

**Typed row results**

```js
const posts = await req.d1`
  SELECT id, title FROM posts ORDER BY id DESC
`.all();
```

## KV

| API | Options |
| --- | --- |
| `get(key, options?)` | `type`: text/json/arrayBuffer/stream; `cacheTtl`; `metadata`: boolean. |
| `put(key, value, options?)` | `expiration`, `expirationTtl`, JSON-serializable `metadata`. |
| `delete(key)` | No options. |
| `list(options?)` | `prefix`, `limit`, `cursor`. |

- **Default KV reads:** Reads return text or null. JSON is parsed only when requested.
- **Metadata result:** Metadata reads return `{ value, metadata, cacheStatus }`. Missing value and metadata are null.
- **List result:** Lists return keys, list\_complete, and an optional cursor.
- **KV completion:** Await all operations.
- **KV keys:** Keys for get/put/delete are non-empty strings.
- **JSON writes:** JSON writes need explicit stringification.
- **Unsupported KV calls:** There is no bulk-get array, string shorthand for options, or separate getWithMetadata method.
- **KV consistency:** KV is eventually consistent, including cached misses. See [KV store](/docs/kv).

## Cache

**Available in Goribu 0.9.0.** `req.cache` needs no binding or configuration. The `GoribuCache` type is exported from `goribu/server`.

| API | Result or options |
| --- | --- |
| `get<Value = unknown>(key)` | Promise of parsed JSON or `null` on a miss. The type argument does not validate stored data. |
| `set(key, value, options?)` | Promise of undefined. JSON serialization; optional positive safe-integer `ttl` in seconds, default 60. |
| `delete(...keys)` | Promise of undefined. Attempts deletion of the supplied keys in the current data center. |

- **Cache keys:** Literal strings starting with `/`, scoped by origin and execution location.
- **Cache failures:** Invalid inputs reject. Platform failures warn and become misses or skipped operations.
- **Pre-rendering:** Pre-rendering bypasses the cache.
- **Background writes:** Use `req.waitUntil` explicitly. See [Cache](/docs/cache) for freshness, Smart Placement, and deployment support.

## Configuration

`defineConfig(config)` validates and returns a frozen configuration. The fields are `name`, `compatibilityDate`, optional `compatibilityFlags`, `database`, `kv`, `r2`, `domain`, `workersDev`, and `responseHeaders`.

**Available in Goribu 0.9.0.** Optional top-level [`domain`](/docs/configuration#custom-domain) connects one application hostname during deployment. **Available in Goribu 0.9.2:** [`workersDev: false`](/docs/configuration#workers-dev-address) turns off the `workers.dev` address and requires `domain`.

- **D1 declaration:** `{ type: "d1", name, replication? }`.
- **KV declaration:** `{ name }`.
- **Header callback:** Receives `{ request, env, mode, nonce }` and synchronously returns a plain object of strings or string arrays. See [Configuration](/docs/configuration) for defaults, allowed names, environment files, and header restrictions.

## CLI

Run from the application directory. The app scripts wrap the installed Goribu CLI.

| Command | Behavior |
| --- | --- |
| `pnpm dev [--port <number>] [--host]` | Local Worker development with Vite. `--port` listens on exactly that port and fails if it is taken; `--host` listens on every network interface (available since 0.9.2). |
| `pnpm build` | Production bundles and static output. |
| `pnpm check` | Read-only production deployment plan. |
| `pnpm run deploy` | Authenticate, build, provision, migrate, and upload. |
| `pnpm exec goribu cloudflare-login` | Log in to Cloudflare through Goribu's installed Wrangler. |
| `pnpm exec goribu tail` | Stream live logs from the deployed Worker. |
| `pnpm exec goribu wrangler <args>` | Run Goribu's installed Wrangler with the account deploy uses. A real `deploy` is refused (available since 0.9.2). |
| `pnpm exec goribu d1 "<sql>"` | Run SQL against local D1. With `--remote`, a single SELECT runs directly and other SQL needs the database name typed in a terminal (available since 0.9.2). |
| `pnpm exec goribu migrate:new <name>` | Create the next numbered SQL migration. |
| `pnpm exec goribu migrate` | Apply pending local migrations. |
| `pnpm exec goribu migrate:status` | Read migration status. |
| `pnpm exec goribu migrate:down` | Roll back one migration. |
| `pnpm exec goribu migrate:seed` | Run local seed.sql; cannot target production. |
| `pnpm exec goribu --help` | Print usage. |
| `pnpm exec goribu --version` | Print the installed version. |

- **Production targets:** Migrate, status, down, and d1 accept `--remote`.
- **Development arguments:** Dev accepts only `--port` and `--host`.
- **Argument-free commands:** Build, check, deploy, tail, and cloudflare-login take no arguments.
- **CLI failures:** Failures exit non-zero. Recognized Goribu failures print their repair message without a stack trace.
- **Type checking:** `pnpm typecheck` is the TypeScript starter's separate `tsc --noEmit` script.
- **Scaffolding:** `pnpm create goribu@latest <name>` creates an app.
- **Scaffolder options:** `--js`, `--help`, and `--goribu-tarball <path>` for a matching local framework archive.
- **Scaffolder scope:** Scaffolding never installs, authenticates, or deploys for you.

## TypeScript

Use `import type`. Types annotate behavior; they do not validate request input or stored JSON.

| Entry | Public types |
| --- | --- |
| `goribu` | LinkProps, NavLinkProps, FormProps, FormMethod, FormState, FormResult, FormErrors, DocumentProps, RouteMetadata, Meta. |
| `goribu/server` | ApplicationConfig, AppRequestFields, DefinedConfig, ResponseHeaders, CookieOptions, Cookies, D1Value, D1WriteResult, D1Statement, D1Queries, D1, KV, GoribuRequest, GoribuResponse, ResponseResult, Handler, Middleware, ServerErrorProps, WorkerContext, WorkerApp, RouteManifestEntry, ClientAsset, AppOptions. |

- **Handler types:** `Handler<Props, Env, Params>` and `Middleware<Env>`.
- **UI types:** `Meta<Props>` and `Form<Data>`.
- **Data types:** `req.d1<Row>` and `req.kv.get<Value>(key, { type: "json" })`.
- **Body validation:** Request body values still need narrowing and validation.

## Low-level app creation

`createApp(options)` from `goribu/server` returns a Worker app with `fetch(request, env, ctx): Promise<Response>`. Normal applications use `goribu()` in Vite; the build supplies the route graph and calls this API for them.

- **Required app options:** `manifest`, `modules`, and `errorPages`.
- **Optional app options:** `documentId`, `middlewareByRoute`, `mode`, `clientAssetManifest`, `clientAssetBase`, and `applicationConfig`.
- **Compiled inputs:** App options describe compiled routes, error pages, assets, and validated config. They are not additional `goribu.config.js` fields.