Bun Backend Boilerplate

A modern backend boilerplate built with Bun, featuring a lightweight HTTP server, PostgreSQL database support, and automated code quality tools.

Features

• Fast Runtime: Powered by Bun for lightning-fast execution
• HTTP Framework: Hono for minimal, fast routing
• Database: PostgreSQL with Kysely query builder
• Type Safety: Full TypeScript support with auto-generated DB types
• Code Quality: Biome for formatting and linting
• Migration System: Kysely migrations and seeds with automatic type generation
• Validation: Zod for environment variables and request validation

Tech Stack

• Bun - JavaScript runtime & toolkit
• Hono - Lightweight web framework
• Kysely - Type-safe SQL query builder
• PostgreSQL - Database
• Biome - Formatter & linter
• Zod - Schema validation

Prerequisites

• Bun (v1.0+)
• PostgreSQL (v12+)

Getting Started

Installation

bun install

Environment Setup

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env with your configuration:

Database Setup

Run migrations to set up your database schema:

bun migrate:latest

Optionally, seed your database:

bun seed:run

Development

Start the development server with hot reload:

bun dev

The server will start on the port specified in your .env file (default: 4000).

Available Scripts

Development

Command	Description
bun dev	Start development server with hot reload
bun route:list	Displays all registered routes. (Optional: --verbose)

Database Operations

Migrations

Command	Description
bun migrate:list	List all migrations
bun migrate:make <name>	Create a new migration
bun migrate:latest	Run all pending migrations + generate types
bun migrate:up	Run next pending migration + generate types
bun migrate:down	Rollback last migration + generate types
bun migrate:rollback	Rollback last batch + generate types

Note: Migration commands automatically run type generation after execution.

Seeds

Command	Description
bun seed:list	List all seeds
bun seed:make <name>	Create a new seed file + format
bun seed:run	Run all seeds

Note: seed:make automatically formats the generated file.

Type Generation

Command	Description
bun db:typegen	Generate TypeScript types from database schema + format

Note: Type generation is automatically triggered after migration commands.

Code Quality

Command	Description
bun format	Format code with Biome
bun lint	Lint code with Biome
bun check	Run all Biome checks

Direct Kysely CLI

Command	Description
bun db	Run kysely CLI directly

Project Structure

.
├── database/
│   ├── migrations/     # Database migrations
│   └── seeds/          # Database seeds
├── src/
│   ├── config.ts       # Environment configuration
│   ├── db.d.ts         # Auto-generated database types
│   └── index.ts        # Application entry point
├── misc/               # Miscellaneous files not directly used by the application
├── .env.example        # Example environment variables
├── biome.json          # Biome configuration
├── kysely.config.ts    # Kysely configuration
├── package.json        # Dependencies and scripts
└── tsconfig.json       # TypeScript configuration

Database Workflow

1. Create Migration: bun migrate:make create_users_table
2. Write Migration: Edit the generated file in database/migrations/
3. Run Migration: bun migrate:latest (automatically generates types)
4. Use Types: Import from src/db.d.ts for type-safe queries