Overview
Relevant source files
The following files were used as context for generating this technical wiki page:
Furin is a React meta-framework powered by Elysia and Bun. It provides a full-stack development environment featuring file-based routing, Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR). The framework focuses on strict TypeScript type inference and high-performance Hot Module Replacement (HMR) using Bun's native capabilities.
Sources: README.md:3-5, AGENTS.md:52-54
Core Architecture
Furin operates as a monorepo containing the core library, documentation, and a scaffolding CLI. The core framework is delivered as an Elysia plugin that bridges the server runtime with React's rendering engine.
Monorepo Structure
| Workspace | Path | Description |
|---|---|---|
| Core | packages/core | Main library containing routing, rendering, and server logic. |
| Scaffolder | apps/scaffolder | CLI tool for creating new Furin projects (bun create furin). |
| Docs | apps/docs | Documentation site. |
| Examples | examples/ | Reference implementations like task managers or weather apps. |
Sources: README.md:21-27, CONTRIBUTING.md:20-25
High-Level Component Relationship
The diagram shows how the core package integrates with a Bun-based Elysia server and scans the application's pages directory.
Sources: AGENTS.md:70-80, packages/core/src/furin.ts:25-30
Key Systems
File-Based Routing and Rendering
Furin scans the pagesDir to build a route map. It supports standard static routes, dynamic segments (e.g., [id].tsx), and nested layouts through root.tsx. Rendering behavior is defined per-route using the config method, allowing developers to switch between SSR, SSG, and ISR.
Sources: AGENTS.md:53-54, packages/core/src/furin.ts:630-650
Document Rendering
Furin manages the HTML document structure through specialized client components. The root layout typically wraps the application using these components to ensure proper hydration and metadata management.
- HeadContent: Injects charsets, viewports, stylesheets, and meta tags into the
<head>. - Scripts: Injects serialized framework data (
__FURIN_DATA__,__FURIN_SYNC__) and the entry module.
Sources: packages/core/src/client/document.tsx:49-140
Data Flow and Hydration
The sequence diagram illustrates the lifecycle of an SSR request, from the initial HTTP GET to React hydration.
Sources: packages/core/src/furin.ts:634-680, packages/core/src/client/router/provider.tsx:180-200
Development Workflow
Furin leverages Bun's native HMR and a custom Bun plugin to avoid full server restarts during route topology changes.
Essential Commands
| Command | Description |
|---|---|
bun run dev | Runs the application with HMR enabled. |
bun run build | Compiles the library or application for production. |
bun run fix | Automatically fixes linting issues via Biome/Ultracite. |
bun run tscheck | Performs static type checking without code emission. |
Sources: CONTRIBUTING.md:10-18, AGENTS.md:57-64
Scaffolding
The create-furin CLI provides two primary templates for quick starting:
- Simple: Minimal setup with Tailwind CSS and a single API route.
- Full: Includes
shadcn/ui, Tailwind, and expanded component structures.
Sources: apps/scaffolder/README.md:38-85
Framework Constraints
- Runtime: Only Bun is supported. Node.js, npm, and other package managers should not be used.
- Styles: Tailwind CSS v4 is integrated via
bun-plugin-tailwind. - Serialization: Uses
serovalfor complex data transfer between server and client.
Sources: CONTRIBUTING.md:7, AGENTS.md:67-75, packages/core/package.json:160