Agent skill

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.

View SKILL.md on GitHub Repository
Stars 3
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/DaleSeo/bun-skills/tree/main/skills/bun-init

Metadata

Additional technical details for this skill

tags
bun javascript typescript initialization setup
author
dale
category
bun-runtime

SKILL.md

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

DaleSeo/bun-skills

deno-to-bun

Migrate Deno projects to Bun with API compatibility analysis. Use when converting Deno.* APIs to Bun equivalents, migrating from Deno Deploy, or updating permissions model and import maps.

3 1
Explore
DaleSeo/bun-skills

bun-build

Create optimized production bundles with Bun's native bundler. Use when building applications for production, optimizing bundle sizes, setting up multi-environment builds, or replacing webpack/esbuild/rollup.

3 1
Explore
DaleSeo/bun-skills

bun-test

Configure Bun's built-in test runner with Jest-compatible APIs. Use when setting up testing infrastructure, writing unit/integration/snapshot tests, migrating from Jest, or configuring test coverage. 3-10x faster than Jest.

3 1
Explore
DaleSeo/bun-skills

cloudflare-to-bun

Migrate Cloudflare Workers to Bun with runtime compatibility analysis. Use when converting Workers to Bun, migrating from Cloudflare bindings, or moving from edge to server deployment.

3 1
Explore
DaleSeo/bun-skills

bun-deploy

Generate optimized Docker images for Bun applications. Use when deploying to containers, minimizing image sizes, setting up CI/CD pipelines, or deploying to Kubernetes.

3 1
Explore
DaleSeo/bun-skills

bun-dev-server

Set up high-performance development servers with Hot Module Replacement. Use when creating dev servers for web apps, setting up React Fast Refresh, or configuring API servers with live reload.

3 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results