Core Features

Furin is a React meta-framework powered by Elysia and Bun. It provides a unified development experience for building web applications with file-based routing and multiple rendering modes, including Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR).

The framework integrates tightly with the Bun runtime to deliver fast Hot Module Replacement (HMR) and full TypeScript type inference across the stack. It functions as an Elysia plugin, making it WinterCG compliant and compatible with various deployment targets.

Sources: README.md:5-7, AGENTS.md:21-25, packages/core/README.md:1-5

File-Based Routing

Furin uses a directory-based structure to define application routes. The scanPages utility discovers route files and normalizes them into deterministic patterns. It supports flat pages, nested layouts, and dynamic segments.

Route Discovery and Ordering

Routes are discovered within a designated pagesDir. The scanner ensures deterministic ordering by sorting patterns alphabetically. Dynamic segments (e.g., [id].tsx) are normalized to parameters (e.g., :id).

The system prevents collisions by throwing errors when two files normalize to the same pattern or when dynamic segments differ only by parameter name.
Sources: packages/core/tests/routing/discovery/scan-order.test.ts:47-98, AGENTS.md:21-23

Rendering Modes

Furin supports three primary rendering strategies defined in the route configuration.

Sources: AGENTS.md:22, packages/core/src/adapter/static.ts:161-205, packages/core/src/adapter/package.ts:79-81

Static Export Logic

The buildStaticTarget function handles the conversion of SSG routes into physical files. It creates an index.html and a __furin_data.ndjson file for every route to enable SPA-style navigation on static hosts like S3 or GitHub Pages.

Document Architecture

The root document structure is managed through the defineRootRoute API. It requires two core components to be rendered within the root layout: <HeadContent /> and <Scripts />.

Component Responsibilities

• HeadContent: Injects metadata, charsets, viewports, stylesheets, and favicon links. It also handles initial theme detection scripts.
• Scripts: Injects serialized framework data (__FURIN_DATA__, __FURIN_SYNC__, __FURIN_HEAD__) and the client-side entry module.

Sources: packages/core/src/client/document.tsx:55-139

Development Experience and HMR

Furin leverages Bun's native HMR capabilities without using Vite. It uses a specialized Bun.plugin to manage page modules in a virtual namespace (furin-dev-page), preventing full server restarts during component edits.

HMR Architecture

The furin-dev-page-loader plugin performs the following actions:

1. Virtual Namespace: Page files are loaded into furin-dev-page to isolate them from Bun's --hot watcher.
2. Singleton Resolution: Rewrites imports for react and react-dom to absolute paths, ensuring only one instance of React exists in the module graph.
3. Transpilation: Uses Bun.Transpiler to transform TSX into JS, injecting JSX helpers and rewriting relative imports.

Packaging and Deployment

The framework provides multiple build targets to suit different deployment needs.

• Bun Target: Standard server build for Bun environments.
• Static Target: Pure HTML/JS/CSS export for static hosting.
• Package Target: Compiles the Furin application into a publishable Elysia plugin.

The Package Target generates a register.js module that bundles page sources while keeping dependencies like @teyik0/furin external, allowing a host application to share the runtime with the plugin.
Sources: packages/core/src/adapter/package.ts:22-38, packages/core/src/adapter/static.ts:327-345

Replayable Mutations (Sync)

Furin implements a furinSync middleware for Elysia that facilitates idempotent mutations. It requires an Idempotency-Key for mutations unless sync: false is explicitly set in the route configuration. This system is designed for multi-host replicas using PostgreSQL or Redis, while supporting SQLite for local development.
Sources: packages/core/README.md:27-33