bun --version

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

2. 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

3. 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": ["@types/bun"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "noImplicitOverride": true
  }
}

For Web Apps:

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

For API Servers:

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

For Libraries:

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

4. 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 (with React):

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

5. 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/

6. Create Environment Template

Create .env.example:

# Application
NODE_ENV=development
PORT=3000

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

7. 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"
  }
}

8. 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

9. 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);
  });
});

10. React Project Shortcut (Bun 1.2.14+)

For React projects, use the --react flag:

bun init --react -y

This creates a project pre-configured with React, JSX support, and appropriate dependencies.

11. Workspace Configuration (Monorepo)

For monorepos with workspaces:

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

Bun supports the same workspace syntax as npm/yarn/pnpm.

Post-Initialization Checklist

After completing the setup, provide the user with:

Confirmation of project type created
List of generated files and directories
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": ["@types/bun"] (not "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
Verbatim Module Syntax: Use "verbatimModuleSyntax": true for cleaner ESM/CJS interop
No Implicit Override: Use "noImplicitOverride": true for safer inheritance

Common Adjustments

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

bun-init

Bun Project Initialization

What's new in Bun 1.4

Core Workflow

1. Check Prerequisites