Developer Tools & Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CONTRIBUTING.md
• README.md
• packages/core/src/server/dev-page-plugin.ts
• packages/core/src/furin.ts
• apps/scaffolder/templates/manifest.json
• apps/scaffolder/README.md
• packages/core/package.json

Furin provides a specialized suite of developer tools and configurations optimized for the Bun runtime. The project centers on high-speed Development Experience (DX) by using Bun's native Hot Module Replacement (HMR) and a custom plugin system that integrates Elysia with React Fast Refresh.

This system manages environment consistency through workspace-wide linting with Biome (via Ultracite) and strict TypeScript type checking. It allows developers to maintain a unified backend and frontend process while ensuring that React singletons remain stable during server-side hot reloads.

Sources: AGENTS.md:32-40, packages/core/src/server/dev-page-plugin.ts:9-30

Core Development Commands

The project uses Bun as the exclusive runtime and task runner. The following table summarizes the primary commands available in the workspace for development, testing, and quality assurance.

Command	Action	Scope
bun run dev	Runs the example application with active HMR.	Examples/Workspace
bun run fix	Automatically fixes linting and formatting issues using Ultracite.	Global
bun run tscheck	Performs TypeScript type-checking without emitting files.	Global
bun run test	Executes all tests across the monorepo.	Global
bun run build	Builds the core library and applications to the dist/ directory.	Global

Sources: AGENTS.md:23-29, CONTRIBUTING.md:14-18, README.md:43-48

Dev-Mode Architecture and HMR

Furin implements a custom Bun.plugin to handle page modules during development. This plugin resolves imports into a virtual namespace (furin-dev-page), which prevents Bun's native --hot watcher from force-restarting the entire server process when only a frontend file changes.

Module Resolution Flow

The development plugin performs several critical transformations to ensure React stability and proper HMR:

1. Virtual Namespace Resolution: It maps .tsx files to the furin-dev-page namespace.
2. Cache Busting: It appends a t=<timestamp> parameter to import specifiers to prevent stale module identities in the Bun ESM registry.
3. Singleton Rewriting: It ensures that react, react-dom, and their internal runtimes always resolve to the exact same on-disk path, preventing "two React copies" errors.

The diagram shows how the system differentiates between page-level changes and core server changes to maintain a fast feedback loop.

Sources: packages/core/src/server/dev-page-plugin.ts:9-55, AGENTS.md:32-35

Singleton Package Management

To prevent hydration mismatches and hook errors, the dev-page-plugin identifies specific packages as singletons.

Package	Purpose
react	Core React library singleton.
react-dom/server	Server-side rendering entry point.
react/jsx-dev-runtime	Development-time JSX transformation.

Sources: packages/core/src/server/dev-page-plugin.ts:74-84

Scaffolding System

The create-furin utility provides an automated pipeline for generating new projects. It uses EJS templates and a manifest-driven architecture to configure dependencies and directory structures.

Available Templates

Furin offers two primary templates for project initialization:

• Simple: Includes Tailwind CSS and a basic API route.
• Full: Includes shadcn/ui, Tailwind CSS, Radix UI primitives, and multiple API routes.

Project Initialization Logic

The scaffolder executes a multi-stage pipeline:

1. Analysis: Validates the project name and target directory.
2. Selection: Interactive choice of templates (simple or full).
3. Dependency Resolution: Maps required packages to the latest validated versions in package-catalog.json.
4. Generation: Renders EJS files and copies static assets while ensuring no path traversal escapes the target directory.

This sequence ensures that the project is immediately ready for development after execution.

Sources: apps/scaffolder/README.md:46-95, apps/scaffolder/templates/manifest.json:6-150, apps/scaffolder/src/pipeline/stages/5-generation.ts:60-95

Tooling Configuration

The framework enforces specific tooling choices to maintain Bun compatibility and high code quality.

• Runtime: Bun only. Usage of Node.js, npm, yarn, or pnpm is explicitly avoided.
• Linting/Formatting: Biome is used via the ultracite wrapper. Configuration resides in biome.jsonc.
• CSS: Tailwind v4 is integrated via bun-plugin-tailwind, configured in bunfig.toml.
• TypeScript: Path aliases are configured in tsconfig.json, where furin maps directly to the core package source for development.

Sources: AGENTS.md:32-40, CONTRIBUTING.md:44-48

Summary of Developer Tooling

Furin integrates several specialized components to create a cohesive development environment:

• furin/strip-plugin: A Bun plugin used in bunfig.toml for static serving.
• evlog: Integrated via packages/core/src/furin.ts to handle structured logging and browser event ingestion.
• furin-env.d.ts: Automatically generated by the framework to provide full TypeScript type inference for application routes.

Sources: AGENTS.md:35-44, packages/core/src/furin.ts:255-275, packages/core/src/server/dev-page-plugin.ts:184-200