Bun Project Initialization Skill

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:

✅ 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": ["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

Agent Skills: Bun Project Initialization

Install this agent skill to your local

Skill Files