bun-init

name	bun-init
description	Initialize a new Bun project with TypeScript and optimal configuration. Use when starting a new Bun project or converting a directory to a Bun project.
compatibility	Requires Bun 1.0+
allowed-tools	["Bash","Write","Read"]
metadata	{"author":"dale","category":"bun-runtime","tags":["bun","javascript","typescript","initialization","setup"]}

Bun Project Initialization

You are assisting with initializing a new Bun project. Follow these steps to create a well-structured project with optimal configurations.

Workflow

1. Check Prerequisites

First, verify Bun is installed:

bun --version

If Bun is not installed, provide installation instructions for the user's platform.

2. Determine Project Type

Ask the user which type of project they want to create:

• CLI Tool: Command-line application with bin entry point
• Web App: Frontend application with React/Vue/etc
• API Server: Backend API with routing framework
• Library: Reusable package for publishing to npm

3. Run Bun Init

Execute the initialization command:

bun init -y

This creates:

• package.json with Bun-optimized scripts
• tsconfig.json with recommended TypeScript settings
• index.ts as the entry point
• README.md with basic project info

4. Enhance TypeScript Configuration

Read the generated tsconfig.json and enhance it based on project type:

For CLI Tools:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["bun-types"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noEmit": true
  }
}

For Web Apps:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "types": ["bun-types"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noEmit": true
  }
}

For API Servers:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["bun-types"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

For Libraries:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["bun-types"],
    "strict": true,
    "declaration": true,
    "declarationMap": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noEmit": true
  }
}

5. Create Project Structure

Generate appropriate directory structure and files:

CLI Tool:

project/
├── src/
│   ├── index.ts          # Main CLI entry point
│   ├── commands/         # Command handlers
│   └── utils/            # Shared utilities
├── tests/
│   └── index.test.ts
├── package.json
├── tsconfig.json
├── .gitignore
├── .env.example
└── README.md

Create src/index.ts:

#!/usr/bin/env bun

console.log("Hello from Bun CLI!");

// Example: Parse command line arguments
const args = process.argv.slice(2);
console.log("Arguments:", args);

Update package.json to add bin field:

{
  "bin": {
    "your-cli-name": "./src/index.ts"
  }
}

Web App:

project/
├── src/
│   ├── index.tsx         # App entry point
│   ├── components/       # React components
│   ├── styles/           # CSS/styles
│   └── utils/            # Utilities
├── public/
│   └── index.html
├── tests/
├── package.json
├── tsconfig.json
├── .gitignore
├── .env.example
└── README.md

API Server:

project/
├── src/
│   ├── index.ts          # Server entry point
│   ├── routes/           # Route handlers
│   ├── middleware/       # Express/Hono middleware
│   ├── services/         # Business logic
│   └── types/            # TypeScript types
├── tests/
├── package.json
├── tsconfig.json
├── .gitignore
├── .env.example
└── README.md

Create src/index.ts:

const server = Bun.serve({
  port: 3000,
  fetch(request) {
    return new Response("Welcome to Bun!");
  },
});

console.log(`Server running at http://localhost:${server.port}`);

Library:

project/
├── src/
│   ├── index.ts          # Main export
│   └── types.ts          # Type definitions
├── tests/
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

6. Create .gitignore

Generate a comprehensive .gitignore:

# Bun
node_modules
bun.lockb
*.bun

# Environment
.env
.env.local
.env.*.local

# Build outputs
dist/
build/
*.tsbuildinfo

# Logs
logs
*.log
npm-debug.log*

# OS
.DS_Store
Thumbs.db

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# Test coverage
coverage/
.nyc_output/

7. Create Environment Template

Create .env.example:

# Application
NODE_ENV=development
PORT=3000

# Add your environment variables here
# DATABASE_URL=
# API_KEY=

8. Update package.json Scripts

Add project-type-specific scripts:

CLI Tool:

{
  "scripts": {
    "dev": "bun run src/index.ts",
    "test": "bun test",
    "lint": "bun run --bun eslint src",
    "typecheck": "bun run --bun tsc --noEmit"
  }
}

Web App:

{
  "scripts": {
    "dev": "bun run --hot src/index.tsx",
    "build": "bun build src/index.tsx --outdir=dist --minify",
    "test": "bun test",
    "typecheck": "bun run --bun tsc --noEmit"
  }
}

API Server:

{
  "scripts": {
    "dev": "bun run --hot src/index.ts",
    "start": "bun run src/index.ts",
    "test": "bun test",
    "typecheck": "bun run --bun tsc --noEmit"
  }
}

Library:

{
  "scripts": {
    "build": "bun build src/index.ts --outdir=dist --minify --sourcemap=external",
    "test": "bun test",
    "typecheck": "bun run --bun tsc --noEmit",
    "prepublishOnly": "bun run build && bun test"
  }
}

9. Install Common Dependencies

Suggest installing common dependencies based on project type:

CLI Tool:

bun add commander chalk ora
bun add -d @types/node

Web App:

bun add react react-dom
bun add -d @types/react @types/react-dom

API Server:

bun add hono
bun add -d @types/node

Library:

# No default dependencies - user will add as needed

10. Create Initial Test File

Create a basic test file in tests/:

import { describe, expect, test } from "bun:test";

describe("Initial test", () => {
  test("basic assertion", () => {
    expect(1 + 1).toBe(2);
  });
});

Post-Initialization Checklist

After completing the setup, provide the user with:

1. ✅ Confirmation of project type created
2. ✅ List of generated files and directories
3. ✅ Next steps:
   • Copy .env.example to .env and configure
   • Run bun install if dependencies were suggested
   • Run bun dev to start development
   • Run bun test to verify tests work

Key Configuration Principles

• Module Resolution: Use "moduleResolution": "bundler" for Bun's native resolution
• TypeScript Types: Always include "types": ["bun-types"]
• No Emit: Set "noEmit": true since Bun runs TypeScript directly
• Import Extensions: Enable "allowImportingTsExtensions": true for .ts imports
• Strict Mode: Enable strict TypeScript checks for better code quality

Common Adjustments

If user wants workspaces (monorepo):

Add to package.json:

{
  "workspaces": ["packages/*"]
}

If user wants path aliases:

Add to tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"]
    }
  }
}

If user wants JSX without React:

Update tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact" // or other JSX runtime
  }
}

Completion

Once all files are created, inform the user that initialization is complete and provide a summary of:

• Project structure
• Available npm scripts
• Recommended next steps
• Links to Bun documentation for their project type