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:

✅ 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

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

bun-init

NPX Install

Tags

SKILL.md Content

Bun Project Initialization

Workflow

1. Check Prerequisites

2. Determine Project Type

3. Run Bun Init

4. Enhance TypeScript Configuration

5. Create Project Structure

6. Create .gitignore

7. Create Environment Template

8. Update package.json Scripts

9. Install Common Dependencies

10. Create Initial Test File

Post-Initialization Checklist

Key Configuration Principles

Common Adjustments

Completion