Furin Framework Documentation
Relevant source files
The following files were used as context for generating this wiki page:
Furin is a React meta-framework powered by Elysia and Bun. It provides file-based routing, full TypeScript type inference, and multiple rendering modes including Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR).
Sources: README.md:1-5, AGENTS.md:37-40
Core Architecture
Furin integrates React frontend components with an Elysia backend as a unified plugin. It utilizes Bun as the sole supported runtime for both development and production. The framework manages the application lifecycle through a centralized compile context that maps logical routes to physical file paths and pre-built assets.
System Components Overview
The following diagram illustrates the relationship between the Furin core, the Elysia server, and the client-side React runtime.
Build and Deployment Targets
Furin supports diverse build targets to accommodate different hosting environments. The furin build command generates artifacts optimized for the specific target.
| Target | Description | Output Artifacts |
|---|---|---|
bun | Standard standalone server for Bun. | server.js, client/ |
static | Full SSG export for static hosts. | index.html per route, _client/ |
package | A publishable Elysia plugin. | index.js, register.js, client/ |
vercel | Deployment artifact for Vercel. | Optimized serverless functions |
node | Compatibility mode for Node.js. | Transpiled JS modules |
Sources: packages/core/src/config.ts:4, packages/core/src/adapter/package.ts:18-35, packages/core/src/cli/index.ts:114-120
Package Build Target
The package target builds a Furin application as a publishable Elysia plugin rather than a bootable server. This allows host applications to compose multiple Furin apps.
Development Mode and HMR
In development, Furin utilizes a custom Bun plugin (furin-dev-page-loader) to handle Hot Module Replacement (HMR) without full server restarts. It intercepts page imports into a virtual namespace (furin-dev-page) to keep them out of Bun's native --hot watcher, preventing hydration mismatches by using cache-busting version parameters.
Dev Loader Flow
- The plugin intercepts requests matching
?furin-server. - It appends a source-version timestamp
&t=<version>to the resolved path. transformDevSourcetranspiles the TSX/JSX usingBun.Transpiler.- Bare specifiers (like
react) are rewritten to absolute paths to ensure singleton instances. - The resulting JS is returned with
loader: "js"to skip further Bun transpilation.
Sources: packages/core/src/server/dev-page-plugin.ts:14-50, packages/core/src/server/dev-page-plugin.ts:250-300
Routing and Data Flow
Furin uses a file-based routing system. Routes are discovered by scanning the pagesDir. Each route can define a loader for data fetching, a layout for UI nesting, and params/query schemas for TypeBox validation.
SPA Navigation Sequence
When a user navigates between pages, the RouterProvider intercepts the request to perform a Single Page Application (SPA) transition.
Configuration
Applications are configured via a furin.config.ts file. This file defines the project structure, plugins, and build preferences.
Configuration Schema
| Option | Type | Default | Description |
|---|---|---|---|
pagesDir | string | "src/pages" | Directory containing route files. |
prefix | string | "" | Mount prefix for the application. |
reactCompiler | boolean | true | Enables Bun's native React Compiler. |
clientLogging | boolean | false | Enables browser event ingest at /_furin/ingest. |
optimizeImports | string[] | [] | Package barrels to parse on demand. |
Sources: packages/core/src/config.ts:40-80, packages/core/src/furin.ts:474-480
Summary
The Furin framework provides a high-performance React meta-framework environment by leveraging Bun's native capabilities. It bridges the gap between server-side Elysia logic and client-side React hydration through a specialized compile context and NDJSON data streaming, supporting flexible deployment targets from static sites to publishable plugins.