Bun Runtime

TriFrost ships with first-class support for Bun, the fast, all-in-one JavaScript runtime. It’s a great choice for modern apps that prioritize speed, native TypeScript, and tight feedback loops.

This guide covers the key things to know when running TriFrost on Bun, including setup specifics, compatibility notes, and best practices.

Why Bun?

Bun brings:

⚡ Blazing-fast startup and execution
🛠 Built-in support for TypeScript, JSX, and module resolution
📦 An integrated package manager (bun install)
🔁 Super-fast watch mode (bun --watch)

TriFrost taps directly into these benefits with:

Native JSX + atomic hydration support
Auto-detection
Built-in Bun adapters (no polyfills needed)
Instant dev feedback with bun run dev

Installation & Hello World

You can scaffold a Bun-powered TriFrost project in seconds:

bun create trifrost@latest

Then choose:

Runtime: Bun
Optional modules: Cache, RateLimiter, Styling, etc.

Or create it manually:

bun add @trifrost/core

import {App} from '@trifrost/core';

new App()
  .get('/', ctx => ctx.text('Hello from Bun!'))
  .boot();

👉 Learn more about the Creation CLI

Bun-Specific Details

Automatic detection

TriFrost detects Bun automatically, no runtime config needed.

TypeScript & JSX Support

Bun supports .ts and .tsx natively. Your tsconfig.json should be set up with:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "jsx": "react-jsx",
    "jsxImportSource": "@trifrost/core",
    ...
  }
}

👉 You don’t need tsc to run your app, just bun run.

Scripts & Watch Mode

The CLI sets up this in your package.json:

{
  "scripts": {
    "dev": "bun run --watch ./src/index.ts",
    "build": "rm -rf ./dist && bun build ./src/index.ts --outdir ./dist"
  }
}

You get instant reloading with:

bun run dev

Container Support (Optional)

TriFrost also supports Podman for containerized Bun development. If enabled during setup, it will:

Scaffold a Containerfile with oven/bun base image
Configure compose.yml with your app on a custom network

podman-compose up

This is useful if you want consistent environments across dev/prod.

Dev Tips

Use .env files for local config
Add TRIFROST_DEV=true in .env to enable dev-mode tracing

👉 Also see: Dev Mode | Environment Config

Gotchas & Recommendations

✅ Make sure you're on Bun v1.1.10+, earlier versions may lack needed stability for streaming, file serving, etc.
🛑 Avoid mixing CommonJS + ESM packages unless you know what you're doing, bun expects full ESM.
✅ Prefer bun install over npm install, bun manages its own lockfile (bun.lockb).
🧪 You can write tests with bun test, but for deeper testing we recommend vitest if needed (it also keeps your test logic agnostic in case you ever want to switch to lets say NodeJS).
✅ JSX hydration is fully supported out-of-the-box with TriFrost's client.css and client.script if configured.

🔧 Generated Project Structure

A default Bun project will include:

/src
  ├── index.ts          ← Entry point
  ├── routes/           ← Route handlers
  ├── components/       ← Layouts and JSX
  ├── css.ts            ← Styling system
  ├── script.ts         ← Scripting system
  ├── types.ts          ← Context/Env/Router types

/public
  ├── logo.svg
  ├── favicon.ico

Containerfile (optional)
compose.yml (optional)
eslint.config.mjs
tsconfig.json
package.json
bun.lockb
.env
.prettierrc

All routes and assets fully scaffolded by the Creation CLI, no config needed.

TLDR

Bun is a great choice for speed and dev velocity
TriFrost has zero-config support for Bun’s runtime and APIs
You can opt into container support if desired
Everything is TypeScript and JSX native

TriFrost Docs