File-based routing

better-router scans src/routes and registers each file on a Hono app. There is no route manifest you edit by hand.

Pages vs APIs

.tsx / .jsx files are React pages.
.md / .mdx files are also pages. Same layouts, middleware, and loaders — see Markdown pages.
.ts / .js files are API routes.
.server.tsx files are never routes. They attach to the page with the same stem (users/[id].tsx + users/[id].server.tsx).

src/routes/index.tsx            →  GET /
src/routes/about.tsx            →  GET /about
src/routes/guide.mdx            →  GET /guide
src/routes/users/[id].tsx       →  GET /users/:id
src/routes/blog/[...slug].tsx   →  GET /blog/*
src/routes/api/hello.ts         →  GET|POST /api/hello

index.tsx in a folder is the folder URL: src/routes/settings/index.tsx → /settings.

Dynamic segments

src/routes/users/[id].tsx

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

export default function UserPage() {
  const { id } = useParams<{ id: string }>();
  return <h1>User {id}</h1>;
}

Catch-all segments use [...slug] and become Hono’s :slug{.*}. The rest of the path is in params.slug. Query strings are not part of the file name. Read them in a loader with c.req.query() or in the page with useQuery().

import type { LoaderArgs } from "better-router";

export function loader({ c }: LoaderArgs) {
  return { tab: c.req.query("tab") ?? "overview" };
}

What is not a route

File	Why
`_layout.tsx`, `_document.tsx`, `_error.tsx`, `_404.tsx`	Special files. `_document.tsx` is the HTML shell — see Layouts
`_middleware.ts`	Nested middleware
`_Card.tsx`	`_` prefix, colocated component
`*.server.tsx`	Server module for a page
`*.d.ts`	Types

Route groups

(admin)/settings.tsx maps to /settings. The (admin) folder is only for organization — useful when two areas should not share a layout folder.

Environment-only routes

src/routes/api/debug.dev.ts     # Vite dev only
src/routes/api/metrics.prod.ts  # production builds

The .dev / .prod suffix is stripped from the URL.

API handlers

API files export HTTP methods. defineHandler turns return values into responses and can take Hono middleware.

src/routes/api/users/index.ts

import { defineHandler, redirect } from "better-router";

export const GET = defineHandler((c) => {
  return { users: [] };
});

export const POST = defineHandler(async (c) => {
  const body = await c.req.json();
  return c.json(body, 201);
});

Return	Response
object / array / number / boolean	JSON `200`
string	HTML `200`
`null` / `undefined`	`204`
`Response` / `c.json(...)`	used as-is (keeps your status)
`redirect("/path")`	`302` (`303` if you pass `redirect(url, 303)`)
`ReadableStream`	streamed body

Pages can export the same HTTP methods from .server.tsx if you want a JSON endpoint on the page URL (for example POST /users/:id next to the HTML page). If both action and POST exist, action wins for form posts.

Validation

defineHandler.withValidator() accepts any Standard Schema library (Zod, Valibot, ArkType):

import * as z from "zod";
import { defineHandler } from "better-router";

export const POST = defineHandler.withValidator({
  body: z.object({ name: z.string().min(1) }),
  query: z.object({ dryRun: z.string().optional() }),
  params: z.object({ id: z.string() }),
})(async (c, { body }) => {
  return { name: body.name };
});

Failed validation throws a 400 with { error: "Validation failed", issues }.

CSS, images, and `public/`

Import CSS from a layout or page. Vite handles it in dev and the client build:

src/routes/_layout.tsx

import "../styles.css";

Put files that should be served as-is in public/ (/favicon.ico, /robots.txt). They land in dist/client. There is no first-class CSS-in-JS runtime. Tailwind is a normal Vite setup: add Tailwind, import its CSS in _document.tsx or the root layout.

TypeScript

See TypeScript for tsconfig and how to share loader props with a page.

Get started

Routing

Rendering

Deploy

Guides

Reference

Pages vs APIs

Dynamic segments

What is not a route

Route groups

Environment-only routes

API handlers

Validation

CSS, images, and `public/`

TypeScript

​Pages vs APIs

​Dynamic segments

​What is not a route

​Route groups

​Environment-only routes

​API handlers

​Validation

​CSS, images, and public/

​TypeScript

Pages vs APIs

Dynamic segments

What is not a route

Route groups

Environment-only routes

API handlers

Validation

CSS, images, and `public/`

TypeScript