akebono

v0.1.0

Published

6 days ago

A small React framework for server-rendered apps with file-based routing, loaders, and Vite integration.

0High
0Medium
0Low

kosei28

react framework ssr router file-based-routing nested-routes layouts loaders vite

akebono

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.

Philosophy and Highlights

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/routes by default. Layouts compose through the route tree, and layout state is preserved when the same layout remains active.
Typed route modules: generated $types files and a route registry provide types for loader args, loader return data, component props, route params, Link, navigate, and path.
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 Request and Response objects.

Installation

npm install akebono react react-dom vite

Quick Start

Add 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.

Routing

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    -> /dashboard

Bracketed directories create params, catch-all params use [...slug], and parenthesized directories create pathless layout groups. Duplicate generated paths are invalid.

Route Modules and Loaders

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.

Navigation

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.

TypeScript

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.

Middleware and Static Files

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.

Build and Deployment

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.

Documentation

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

akebono

Philosophy and Highlights

Installation

Quick Start

Routing

Route Modules and Loaders

Navigation

TypeScript

Middleware and Static Files

Build and Deployment

Documentation

License