Loaders and actions

Each page can have a companion .server.tsx file. That module never ships to the browser.

src/routes/projects/[id].tsx
src/routes/projects/[id].server.tsx

Loaders

loader runs on GET. Its return value becomes the page component’s props and useLoaderData().

src/routes/projects/[id].server.tsx

import type { LoaderArgs } from "better-router";
import { getEnv, redirect } from "better-router";

export async function loader({ params, c }: LoaderArgs) {
  const id = params.id!;
  const db = getEnv().DB as D1Database;
  const row = await db.prepare("select id, name from projects where id = ?").bind(id).first();
  if (!row) return redirect("/projects");
  const tab = c.req.query("tab") ?? "overview";
  return { project: row, tab };
}

src/routes/projects/[id].tsx

import { useLoaderData } from "better-router/react";

export default function ProjectPage() {
  const { project } = useLoaderData<{ project: { name: string } }>();
  return <h1>{project.name}</h1>;
}

LoaderArgs:

Field	What it is
`c`	Hono context. Cookies, headers, `c.env`, `c.set` / `c.get`
`params`	Dynamic segments (`{ id: "abc" }`)
`request`	The raw `Request`

redirect("/login") from a loader sends the browser there. Prefer that for HTML pages. Throw HTTPException(401) from APIs — see Errors.

Actions

action handles POST, PUT, PATCH, and DELETE for the same URL. Named actions live on actions and are selected with ?action= or ?_action=.

src/routes/projects/[id].server.tsx

import type { ActionArgs } from "better-router";
import { getEnv, redirect } from "better-router";

export async function action({ params, formData }: ActionArgs) {
  const name = String(formData?.get("name") ?? "");
  const db = getEnv().DB as D1Database;
  await db.prepare("update projects set name = ? where id = ?").bind(name, params.id!).run();
  return redirect(`/projects/${params.id}`);
}

export const actions = {
  archive: async ({ params }: ActionArgs) => {
    const db = getEnv().DB as D1Database;
    await db.prepare("update projects set archived = 1 where id = ?").bind(params.id!).run();
    return redirect("/projects");
  },
};

After an action:

Return	What the browser does
`redirect("/path")`	SPA navigate (or `303` document redirect on island pages)
object	Re-renders the page with that object as loader data (SPA JSON payload or HTML document)
`undefined` / no return	Re-runs the loader and re-renders
`Response`	used as-is

Use redirect(url, 303) after POST so the browser does not replay the form. redirect(url) is 302.

Forms

import { Form } from "better-router/react";

export default function EditProject() {
  return (
    <Form method="post">
      <input name="name" />
      <button type="submit">Save</button>
      <button type="submit" formAction="?action=archive">
        Archive
      </button>
    </Form>
  );
}

<Form> intercepts submit, posts multipart/urlencoded as the browser would, and follows redirects through the SPA router. Add data-enhance="false" on a submitter to do a full document post. useForm() is a small controlled helper (data, errors, pending, post(url)). It treats HTTP 422 as field errors. Island pages should use useIslandForm() — same API, but a successful action reloads the document.

File uploads

<Form method="post" encType="multipart/form-data">
  <input type="file" name="avatar" accept="image/*" />
  <button type="submit">Upload</button>
</Form>

import type { ActionArgs } from "better-router";
import { getEnv, redirect } from "better-router";

export async function action({ formData }: ActionArgs) {
  const file = formData?.get("avatar");
  if (!(file instanceof File) || file.size === 0) return redirect("/settings");
  const key = `avatars/${crypto.randomUUID()}`;
  const bucket = getEnv().BUCKET as R2Bucket;
  await bucket.put(key, await file.arrayBuffer(), {
    httpMetadata: { contentType: file.type || "application/octet-stream" },
  });
  return redirect("/settings");
}

See Bindings for R2.

Cookies and headers

There is no wrapper around cookies. Use Hono’s helpers on c:

import type { ActionArgs } from "better-router";
import { setCookie, getCookie } from "hono/cookie";

export async function loader({ c }: ActionArgs) {
  return { locale: getCookie(c, "locale") ?? "en" };
}

export async function action({ c, formData }: ActionArgs) {
  setCookie(c, "locale", String(formData?.get("locale") ?? "en"), {
    path: "/",
    httpOnly: true,
    sameSite: "Lax",
  });
  return { ok: true };
}

Render flags

Export these from the .server.tsx file:

export const ssr = false;      // send an empty #app, render on the client
export const spa = false;      // always do a full document navigation
export const hydrate = false;  // static HTML, skip client runtime

prerender is reserved and not implemented. Do not export it expecting a static snapshot.

Request-scoped helpers

Inside a loader, action, or middleware you can call:

import { getEnv, getHonoContext } from "better-router";

They use AsyncLocalStorage. They throw from a scheduled / queue / email handler — pass env from defineWorker instead. See Worker entrypoint.

Get started

Routing

Rendering

Deploy

Guides

Reference

Loaders

Actions

Forms

File uploads

Cookies and headers

Render flags

Request-scoped helpers

​Loaders

​Actions

​Forms

​File uploads

​Cookies and headers

​Render flags

​Request-scoped helpers

Loaders

Actions

Forms

File uploads

Cookies and headers

Render flags

Request-scoped helpers