# Bun Init

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

- Skill: `involvex/bun-init-2` (Agent Skill)
- Install (CLI): `npx get-skill add involvex/bun-init-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/involvex/bun-init-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: involvex (https://skillmd.com/u/involvex)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/involvex/bun-init-2

---


# 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:

```bash
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:

```bash
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:**

```json
{
	"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:**

```json
{
	"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:**

```json
{
	"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:**

```json
{
	"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`:

```typescript
#!/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:

```json
{
	"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`:

```typescript
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`:

```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`:

```bash
# 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:**

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

**Web App:**

```json
{
	"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:**

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

**Library:**

```json
{
	"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:**

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

**Web App:**

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

**API Server:**

```bash
bun add hono
bun add -d @types/node
```

**Library:**

```bash
# No default dependencies - user will add as needed
```

### 10. Create Initial Test File

Create a basic test file in `tests/`:

```typescript
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`:

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

**If user wants path aliases:**

Add to `tsconfig.json`:

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

**If user wants JSX without React:**

Update `tsconfig.json`:

```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

