Quickstart

This gets a page, a loader, and an API route running.

1. Install

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install better-router@alpha hono

Or add the same packages to an existing Vite app: better-router@alpha, hono, react, react-dom, and vite.

2. Enable the plugin

Replace the default Vite plugin list with betterRouter(). It already includes @vitejs/plugin-react.

vite.config.ts

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

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

package.json

{
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

src/vite-env.d.ts

/// <reference types="vite/client" />
/// <reference types="better-router/client" />

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "types": ["vite/client"]
  },
  "include": ["src", ".better-router", "vite.config.ts"]
}

Delete Vite’s index.html and src/main.tsx. Pages live in src/routes, not a client entry. Full compiler options are in TypeScript.

3. Layout and page

Layouts wrap the page tree. They do not render <html> or <body> — that is _document.tsx, or the default document the plugin already provides.

src/routes/_layout.tsx

import type { ReactNode } from "react";
import { Link } from "better-router/react";

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <div>
      <nav>
        <Link href="/">Home</Link>
      </nav>
      {children}
    </div>
  );
}

src/routes/index.tsx

type HomeProps = { message: string };

export default function Home({ message }: HomeProps) {
  return <h1>{message}</h1>;
}

src/routes/index.server.tsx

export function loader() {
  return { message: "Hello from better-router" };
}

Loader data is passed as page props and available from useLoaderData(). Use whichever you prefer. The .server.tsx file never ships to the browser.

4. API route

src/routes/api/hello.ts

import { defineHandler } from "better-router";

export const GET = defineHandler(() => {
  return { ok: true };
});

Objects become JSON. See Routing for redirects, status codes, and validation.

5. Run it

npm run dev

App: http://localhost:5173
API: http://localhost:5173/api/hello

The first page request is SSR HTML. Clicks on <Link> fetch JSON and swap the page on the client.

vite build emits dist/client (assets) and dist/server (the Worker module). To deploy that to Cloudflare, see Cloudflare Workers.

What you add next

Goal	Page
Nested routes, params, groups	Routing
Shared chrome and HTML document	Layouts
Forms and mutations	Loaders and actions
Cloudflare deploy	Cloudflare Workers
Bindings on `env`	Bindings
Cron, queues, inbound email	Worker entrypoint

Get started

Routing

Rendering

Deploy

Guides

Reference

1. Install

2. Enable the plugin

3. Layout and page

4. API route

5. Run it

What you add next

​1. Install

​2. Enable the plugin

​3. Layout and page

​4. API route

​5. Run it

​What you add next

1. Install

2. Enable the plugin

3. Layout and page

4. API route

5. Run it

What you add next