Bun Monorepo Development Skill

Overview

Expert guidance for managing Bun monorepos with Workspaces and Changesets for version management.

When to Use This Skill

• Setting up or managing Bun workspaces
• Managing dependencies across packages
• Creating new packages in the monorepo
• Version management with Changesets
• Generating changelogs and releases

Stack Context

• Runtime: Bun
• Monorepo: Bun Workspaces
• Version Management: Changesets
• Code Style: Standard JS (no semicolons)
• Package Manager: Bun

Project Structure

.
├── package.json (root workspace)
├── bun.lockb
├── .changeset/
│   └── config.json
└── packages/
    ├── service-a/
    │   ├── package.json
    │   ├── CHANGELOG.md
    │   └── src/
    └── service-b/
        ├── package.json
        ├── CHANGELOG.md
        └── src/

Workflows

1. Initialize Monorepo

# Create root package.json with workspaces
bun init -y

# Add workspace configuration

Root package.json:

{
  "name": "monorepo-root",
  "workspaces": ["packages/*"],
  "scripts": {
    "changeset": "changeset",
    "version": "changeset version",
    "release": "changeset publish"
  },
  "devDependencies": {
    "@changesets/cli": "^2.27.1"
  }
}

Initialize Changesets:

bun add -D @changesets/cli
bunx changeset init

2. Create New Package

# Create package directory
mkdir -p packages/my-service
cd packages/my-service

# Initialize package
bun init -y

Package package.json:

{
  "name": "@monorepo/my-service",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "bun --watch src/index.js",
    "start": "bun src/index.js",
    "lint": "standard"
  }
}

3. Managing Dependencies

Install dependency for specific package:

# From root
bun add <package> --cwd packages/my-service

# Or from package directory
cd packages/my-service
bun add <package>

Add dev dependency:

bun add -D <package> --cwd packages/my-service

Link internal packages:

{
  "dependencies": {
    "@monorepo/shared": "workspace:*"
  }
}

Install all dependencies:

# From root
bun install

4. Version Management with Changesets

Create a changeset:

bunx changeset

Follow the prompts:

1. Select which packages changed
2. Choose bump type (patch/minor/major)
3. Write summary of changes

Version packages (bump versions & update changelogs):

bunx changeset version

This will:

• Update version in package.json
• Generate/update CHANGELOG.md
• Remove consumed changeset files

Publish (if publishing to npm):

bunx changeset publish

5. Changeset Configuration

.changeset/config.json:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Independent versioning (recommended):

• Each package has its own version
• Packages are released independently
• Default configuration

Fixed versioning:

{
  "fixed": [["@monorepo/service-a", "@monorepo/service-b"]]
}

6. Running Scripts Across Packages

Run script in specific package:

bun run --cwd packages/my-service dev

Using --filter to run commands in specific packages:

# Run dev script in a specific package
bun --filter @monorepo/service-a dev

# Run test in multiple packages
bun --filter @monorepo/service-a --filter @monorepo/service-b test

# Run script in all packages matching pattern
bun --filter "@monorepo/*" lint

# Run script in all packages (if no filter specified)
bun --filter "*" test

Install dependencies with filter:

# Install dependency only in specific package
bun --filter @monorepo/service-a add express

# Install dev dependency in specific package
bun --filter @monorepo/service-a add -D @types/node

# Install in multiple packages
bun --filter @monorepo/service-a --filter @monorepo/service-b add lodash

Run commands with workspace dependencies:

# Build all packages including their workspace dependencies
bun --filter @monorepo/web... build

# This will build @monorepo/web AND any workspace packages it depends on

Advanced filtering:

# Run in changed packages only (since last commit)
bun --filter "[HEAD^1]" test

# Run in packages that depend on a specific package
bun --filter "...@monorepo/shared" build

# Exclude specific packages
bun --filter "!@monorepo/service-a" test

Run script in all packages (manual approach):

# Sequential
cd packages/service-a && bun run dev
cd packages/service-b && bun run dev

# Parallel (background jobs)
cd packages/service-a && bun run dev &
cd packages/service-b && bun run dev &

Or use a script in root package.json:

{
  "scripts": {
    "dev:service-a": "bun --filter @monorepo/service-a dev",
    "dev:service-b": "bun --filter @monorepo/service-b dev",
    "dev:all": "bun --filter \"@monorepo/*\" dev",
    "build": "bun --filter \"@monorepo/*\" build",
    "test": "bun --filter \"@monorepo/*\" test",
    "lint": "bun --filter \"@monorepo/*\" lint"
  }
}

7. Git Tagging Convention

Format: service-name@vX.X.X

After changesets version:

# Review version changes
git diff

# Commit version changes
git add .
git commit -m "chore: version packages"

# Create tags for changed packages
git tag service-a@v1.2.0
git tag service-b@v0.3.1

# Push with tags
git push --follow-tags

8. Common Tasks

Add shared package:

mkdir -p packages/shared/src
cd packages/shared
bun init -y

{
  "name": "@monorepo/shared",
  "version": "0.1.0",
  "type": "module",
  "exports": {
    ".": "./src/index.js"
  }
}

Use shared package:

{
  "dependencies": {
    "@monorepo/shared": "workspace:*"
  }
}

import { something } from '@monorepo/shared'

Best Practices

1. Versioning Strategy:

   • Use independent versioning for services
   • Use fixed versioning for tightly coupled packages
   • Always create changesets before merging PRs

2. Dependencies:

   • Use workspace:* protocol for internal dependencies
   • Keep external dependencies aligned across packages when possible
   • Use updateInternalDependencies: "patch" in changeset config

3. Changesets Workflow:

   • Create changeset per PR: bunx changeset
   • Run bunx changeset version on main after merge
   • Automate with CI/CD (see DevOps skill)

4. Code Style:

   • Use Standard JS (no semicolons)
   • Share linter config from root or shared package
   • Run linting from root: standard 'packages/*/src/**/*.js'

5. Scripts:

   • Define common scripts in root for all packages
   • Use --filter flag to target specific packages or patterns
   • Use --cwd flag for directory-specific commands
   • Leverage filter patterns for efficient monorepo operations

Troubleshooting

Dependencies not resolving:

# Clear cache and reinstall
rm -rf node_modules bun.lockb
bun install

Workspace link not working:

• Ensure package name matches in package.json
• Use workspace:* protocol
• Run bun install from root

Changeset not detecting changes:

• Ensure you're in a git repository
• Check .changeset/config.json for ignored packages
• Verify package.json has correct name

References

• Bun Workspaces Docs
• Changesets Documentation
• Standard JS Style Guide