akebono is a small React framework for server-rendered apps. It gives you file-based routes, nested layouts, server loaders, hydrated client navigation, typed route helpers, middleware, static file serving, and Vite integration without introducing React Server Components.
- No RSC by design: route modules are ordinary React components plus server loaders. akebono keeps the mental model close to React, HTTP, and plain module exports.
- MPA-like data flow: server loaders run for normal navigations instead of relying on a framework-managed loader cache. Client navigation hydrates the page and requests fresh JSON data.
- File-based routes and nested layouts: routes live under
src/routesby default. Layouts compose through the route tree, and layout state is preserved when the same layout remains active. - Typed route modules: generated
$typesfiles and a route registry provide types for loader args, loader return data, component props, route params,Link,navigate, andpath. - Small Vite-first surface area: akebono focuses on routing, rendering, loaders, navigation, middleware, static files, and Vite integration.
- Fetch-compatible core: request handlers, middleware, and deploy entries
use standard
RequestandResponseobjects.
npm install akebono react react-dom viteAdd the Vite plugin:
// vite.config.ts
import { defineConfig } from "vite";
import { akebono } from "akebono/vite";
export default defineConfig({
plugins: [akebono()]
});Create a root layout:
// src/routes/layout.tsx
import { Head, Script } from "akebono/client";
import type { LayoutProps } from "./$types";
export default function Layout({ children }: LayoutProps) {
return (
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<Head>
<title>akebono app</title>
</Head>
</head>
<body>
{children}
<Script />
</body>
</html>
);
}Create a page with optional server data:
// src/routes/page.tsx
import { Head } from "akebono/client";
import type { PageLoaderArgs, PageProps } from "./$types";
export async function loader(_args: PageLoaderArgs) {
return {
message: "Hello from the server"
};
}
export default function HomePage({ data }: PageProps) {
return (
<main>
<Head>
<title>{data.message}</title>
</Head>
<h1>{data.message}</h1>
</main>
);
}For the full setup, including TypeScript configuration, see Getting Started.
Every page.* file creates a URL route. Directories can also contain
layout.* and error.* modules.
src/routes/page.tsx -> /
src/routes/users/page.tsx -> /users
src/routes/users/[id]/page.tsx -> /users/:id
src/routes/docs/[...slug]/page.tsx -> /docs/**:slug
src/routes/(app)/dashboard/page.tsx -> /dashboardBracketed directories create params, catch-all params use [...slug], and
parenthesized directories create pathless layout groups. Duplicate generated
paths are invalid.
Read more in Routing.
page.*, layout.*, and error.* files are route modules. Pages and layouts
may export a server-side loader; the default export is the React component.
Loaders receive request, url, params, context, and parentData.
Layout loaders run from the root layout down to the page, and each child loader
receives the shallow-merged data from ancestor layout loaders.
Loader data must be JSON-serializable. Loaders may also return or throw
Response values through helpers such as json, redirect, status, and
notFound.
Read more in Route Modules.
Use Link, navigate, and reloadData from akebono/client for hydrated
client-side navigation. Client navigations request JSON loader data, follow
same-origin redirects, update navigation state, and restore scroll positions.
import { Link, navigate } from "akebono/client";
<Link to="/users/:id" params={{ id: "42" }}>
User 42
</Link>;
await navigate("/users/:id", {
params: { id: "42" },
search: { tab: "activity" }
});Use path from akebono or akebono/client when you only need to build a
URL string.
Read more in Navigation.
akebono generates route-local $types files and a global route registry under
.akebono/types.
{
"compilerOptions": {
"rootDirs": ["src/routes", ".akebono/types/routes"]
},
"include": ["src", ".akebono/types/**/*.d.ts", "vite.config.ts"]
}Start Vite or run a build once so the generated types exist. After that,
route modules can import local types from ./$types, and path, Link, and
navigate get typed params from the generated registry.
Read more in TypeScript.
The Vite plugin can discover src/middleware.ts, or you can configure one or
more middleware files explicitly. Middleware runs before route matching and is
the recommended place to forward API requests.
In production output, built static files are served before middleware and
routes. Custom integrations can use createStaticFileHandler.
Read more in Middleware and Static Files.
During development, akebono/vite discovers routes, generates route types,
serves SSR HTML, serves JSON data requests, runs middleware, and watches route
files.
During vite build, akebono writes a manifest, generated types, a client
entry chunk, and a Fetch-compatible server entry under .akebono. The Vite
plugin also includes integration support for Nitro and Cloudflare Workers.
Read more in Vite and Build.
- Documentation Home
- Getting Started
- Routing
- Route Modules
- Navigation
- Middleware and Static Files
- Vite and Build
- TypeScript
- API Reference
MIT