What is better-router?

This is the first public alpha. APIs may change. Install better-router@alpha and pin the version you ship.

better-router is a fullstack Vite plugin. Files in src/routes become pages and API endpoints. Every request runs through Hono. Loader data is typed into React pages. The same tree can run on Node, Bun, Deno, or Cloudflare Workers. The source tree is the app. The plugin generates the server. You do not maintain a central router file.

What it gives you

File-based routing

Pages live in src/routes. _layout.tsx wraps nested UI. Companion .server.tsx files hold loaders and actions.

Hono on the server

Global middleware in src/middleware and nested _middleware.ts files use (c, next). API routes export GET / POST.

SSR, then SPA

The first load is HTML. <Link> navigations fetch JSON and swap the page. Island pages hydrate only the widgets you mark.

Cloudflare Workers

vite build emits a Worker with fetch. Bindings land on getEnv(). Optional scheduled, queue, and email handlers live in src/worker.ts.

Where things go

You need	Put it here	Call this
A page	`src/routes/dashboard.tsx`	default export
Server data / mutations	`src/routes/dashboard.server.tsx`	`loader` / `action`
HTML shell	`src/routes/_document.tsx`	default export
JSON API	`src/routes/api/webhooks/stripe.ts`	`export const POST`
Worker handlers	`src/worker.ts`	`defineWorker()`
Bindings	`wrangler.jsonc`	`getEnv()` / `c.env`

Routes and middleware are the only required folders. Add wrangler.jsonc when you deploy to Cloudflare.

Mental model

vite.config.ts                 betterRouter()
src/routes/*.tsx               React pages (SSR HTML, then SPA)
src/routes/*.{md,mdx}          Markdown pages (same layouts and loaders)
src/routes/_document.tsx       HTML shell (`<html>`, `<head>`, `<body>`)
src/routes/*.server.tsx        loaders and actions (server only)
src/routes/api/*.ts            Hono HTTP handlers
src/middleware/*.ts            Hono middleware
src/worker.ts                  Worker fetch / scheduled / queue / email (Cloudflare)
wrangler.jsonc                 Cloudflare deploy + bindings

The plugin scans those files, generates a Hono app, and hydrates the client.

Install

npm install better-router@alpha hono react react-dom
npm install -D vite

vite.config.ts

import { defineConfig } from "vite";
import { betterRouter } from "better-router/plugin";

export default defineConfig({
  plugins: [betterRouter()],
});

Put pages in src/routes and middleware in src/middleware. Then run vite. Full walkthrough: Quickstart. For Workers, see Cloudflare.

Next steps

Quickstart

Add the plugin, a page, a loader, and an API route.

Cloudflare Workers

Build a Worker, point Wrangler at it, and deploy.

Bindings

Declare D1, KV, R2, and secrets in Wrangler. Read them with getEnv().

Worker entrypoint

defineWorker for fetch, cron, queues, and inbound email.

Get started

Routing

Rendering

Deploy

Guides

Reference

What it gives you

File-based routing

Hono on the server

SSR, then SPA

Cloudflare Workers

Where things go

Mental model

Install

Next steps

Quickstart

Cloudflare Workers

Bindings

Worker entrypoint

​What it gives you

File-based routing

Hono on the server

SSR, then SPA

Cloudflare Workers

​Where things go

​Mental model

​Install

​Next steps

Quickstart

Cloudflare Workers

Bindings

Worker entrypoint

What it gives you

Where things go

Mental model

Install

Next steps