Furin Documentation

Furin is a React meta-framework built on Bun and Elysia. It adds file-based pages, nested layouts, typed server loaders, SPA navigation, SSR, SSG, and ISR without putting a second application server or a Vite proxy beside your Elysia app.

import { Elysia } from "elysia";
import { furin } from "@teyik0/furin";

new Elysia()
  .use(await furin({ pagesDir: "./src/pages" }))
  .get("/api/health", () => ({ ok: true }))
  .listen(3000);

The Mental Model

A Furin application has three layers:

1. Elysia owns HTTP. Authentication, API routes, WebSockets, middleware, and lifecycle hooks remain regular Elysia plugins.
2. The file tree owns pages. Files in src/pages define URLs, layouts, loading, metadata, and rendering modes.
3. Bun owns development and builds. The dev server uses Bun's full-stack HTML bundler and React Fast Refresh; production builds use Bun's bundler or static exporter.

A page declares its contract in one chain:

import { defineRoute } from "@teyik0/furin";

export const route = defineRoute("/")
  .config({ mode: "ssr" })
  .loader(async ({ log }) => {
    log.set({ feature: "home" });
    return { message: "Hello from the server" };
  })
  .head(({ message }) => ({ meta: [{ title: message }] }))
  .page(({ message }) => <h1>{message}</h1>);

config() is mandatory. The builder then carries layout data, route params, validated search state, loader output, and requestLoader() output into the next stage.

What Furin Is Good At

• Bun and Elysia are deliberate platform choices.
• Pages and APIs should share one process and one origin.
• Route-level rendering should be explicit rather than inferred from component usage.
• Runtime validation and TypeScript inference should come from the same TypeBox schemas.
• Teams want static pages, request-rendered pages, and incrementally regenerated pages in one route model.

Furin is currently an alpha framework and supports Bun only. The production outputs are a Bun server, Bun executable, self-contained executable, Vercel Bun Function, static export, and packaged Furin app.

Start Here

• Getting Started creates and runs an application.
• File-Based Routing explains the route tree and generated types.
• Data Loading covers public and request-private data.
• Rendering Modes helps choose SSR, SSG, or ISR.
• Comparison gives a candid Next.js and TanStack Start comparison.