Bun

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bun Skill Reference

## Product Summary

Bun is an all-in-one JavaScript/TypeScript toolkit that replaces Node.js, npm, and bundlers with a single fast binary. It includes a runtime (powered by JavaScriptCore), package manager, test runner, and bundler. Key files: `bunfig.toml` (configuration), `package.json` (scripts and dependencies), `bun.lock` (lockfile). Primary CLI commands: `bun run`, `bun install`, `bun test`, `bun build`. See https://bun.com/docs for comprehensive documentation.

## When to Use

- **Running scripts**: Execute `.js`, `.ts`, `.jsx`, `.tsx` files directly with `bun run` or `bun <file>` — no compilation step needed
- **Package management**: Install dependencies with `bun install` (25x faster than npm) or add packages with `bun add`
- **Testing**: Write and run Jest-compatible tests with `bun test` with TypeScript support built-in
- **Bundling**: Bundle applications for browsers or servers with `bun build` or `Bun.build()` API
- **HTTP servers**: Build servers with `Bun.serve()` API with native WebSocket and streaming support
- **Monorepos**: Manage workspaces with `bun install --filter` and run scripts across packages
- **Development**: Use watch mode (`--watch`) for live reloading during development
- **Deployment**: Compile standalone executables with `bun build --compile` or deploy to Vercel, Railway, etc.

## Quick Reference

### Essential Commands

| Task | Command |
|------|---------|
| Run a file | `bun run index.ts` or `bun index.ts` |
| Run a script | `bun run dev` (from package.json) |
| Install dependencies | `bun install` |
| Add a package | `bun add react` or `bun add -d @types/node` |
| Remove a package | `bun remove react` |
| Run tests | `bun test` |
| Watch tests | `bun test --watch` |
| Build for browser | `bun build ./index.tsx --outdir ./dist` |
| Build for server | `bun build ./index.tsx --outdir ./dist --target bun` |
| Watch build | `bun build ./index.tsx --outdir ./dist --watch` |
| Run with watch mode | `bun --watch run index.ts` |
| Execute a package | `bunx cowsay "Hello"` |

### Configuration Files

| File | Purpose |
|------|---------|
| `bunfig.toml` | Bun-specific configuration (optional, zero-config by default) |
| `package.json` | Project metadata, scripts, dependencies |
| `bun.lock` | Lockfile (text-based, replaces package-lock.json) |
| `tsconfig.json` | TypeScript configuration (Bun respects this) |

### Key bunfig.toml Sections

```toml
[install]
linker = "hoisted"  # or "isolated" for strict dependency isolation
dev = true          # install devDependencies
optional = true     # install optionalDependencies
peer = true         # install peerDependencies

[test]
root = "."
coverage = false
coverageThreshold = 0.9

[run]
shell = "system"    # or "bun" for Bun's shell
bun = true          # alias node to bun in scripts
```

### File Type Support

Bun natively transpiles and executes:
- `.js`, `.jsx` — JavaScript and JSX
- `.ts`, `.tsx` — TypeScript and TSX
- `.json`, `.jsonc`, `.toml`, `.yaml` — Data files (parsed at build time)
- `.html` — HTML with asset bundling
- `.css` — CSS bundling

## Decision Guidance

| Scenario | Use | Why |
|----------|-----|-----|
| **Package installation** | `bun install` vs `npm install` | Bun is 25x faster, uses global cache, supports workspaces |
| **Linker strategy** | `--linker isolated` vs `--linker hoisted` | Isolated prevents phantom dependencies; hoisted is traditional npm behavior |
| **Build target** | `--target browser` vs `--target bun` vs `--target node` | Browser for web apps, bun for server code, node for Node.js compatibility |
| **Module format** | `--format esm` vs `--format cjs` | ESM is default; use CJS for CommonJS compatibility |
| **Watch mode** | `--watch` vs manual restart | Use `--watch` for development; Bun uses OS-native file watchers (fast) |
| **Test execution** | `--concurrent` vs sequential | Concurrent for independent tests; sequential for tests with shared state |
| **Bundling** | `bun build` vs `Bun.build()` API | CLI for simple builds; API for programmatic control and in-memory bundling |

## Workflow

### 1. Initialize a Project
```bash
bun init my-app
cd my-app
```
Choose template: Blank, React, or Library. Creates `package.json`, `tsconfig.json`, `bunfig.toml`.

### 2. Install Dependencies
```bash
bun install
# or add specific packages
bun add react
bun add -d @types/node typescript
```
Generates `bun.lock` lockfile. Use `--frozen-lockfile` in CI for reproducible builds.

### 3. Write Code
Create `.ts`, `.tsx`, `.js`, or `.jsx` files. Bun transpiles on the fly.

### 4. Run Code
```bash
bun run index.ts
# or with watch mode
bun --watch run index.ts
```

### 5. Add Scripts to package.json
```json
{
  "scripts": {
    "dev": "bun --watch run src/index.ts",
    "build": "bun build ./src/index.tsx --outdir ./dist",

From youssefKadaouiAbbassi/yka-code, MIT.

More from youssefKadaouiAbbassi/yka-code