Node.js to Bun Migration

You are assisting with migrating an existing Node.js project to Bun. This involves analyzing dependencies, updating configurations, and ensuring compatibility.

Migration Workflow

1. Pre-Migration Analysis

Check if Bun is installed:

bash

bun --version

Analyze current project:

bash

# Check Node.js version
node --version

# Check package manager
ls -la | grep -E "package-lock.json|yarn.lock|pnpm-lock.yaml"

Read package.json to understand the project structure.

2. Dependency Compatibility Check

Read and analyze all dependencies from package.json:

bash

cat package.json

Check for known incompatible native modules:

Common problematic packages (check against current dependencies):

•bcrypt → Use bcryptjs or @node-rs/bcrypt instead
•sharp → Bun has native support, but may need version check
•node-canvas → Limited support, check version compatibility
•sqlite3 → Use bun:sqlite instead
•node-gyp dependent packages → May require alternative pure JS versions
•fsevents → macOS-specific, usually optional dependency
•esbuild → Bun has built-in bundler, may be redundant

Check workspace configuration (for monorepos):

bash

# Check if workspaces are defined
grep -n "workspaces" package.json

3. Generate Compatibility Report

Create a migration report file BUN_MIGRATION_REPORT.md:

markdown

# Bun Migration Analysis Report

## Project Overview
- **Name**: [project name]
- **Current Node Version**: [version]
- **Package Manager**: [npm/yarn/pnpm]
- **Project Type**: [app/library/monorepo]

## Dependency Analysis

### ✅ Compatible Dependencies
[List dependencies that are Bun-compatible]

### ⚠️ Potentially Incompatible Dependencies
[List dependencies that may have issues]

**Recommended Actions:**
- [Specific migration steps for each incompatible dependency]

### 🔄 Recommended Replacements
[List suggested package replacements]

## Configuration Changes Needed

### package.json
- [ ] Update scripts to use `bun` instead of `npm`/`yarn`
- [ ] Review and update `engines` field
- [ ] Check `type` field (ESM vs CommonJS)

### tsconfig.json
- [ ] Update `moduleResolution` to `"bundler"`
- [ ] Add `bun-types` to types array
- [ ] Set `allowImportingTsExtensions` to `true`

### Build Configuration
- [ ] Review webpack/rollup/esbuild config (may use Bun bundler)
- [ ] Update test runner config (use Bun test instead of Jest)

## Migration Steps

1. Install Bun dependencies
2. Update configuration files
3. Run tests to verify compatibility
4. Update CI/CD pipelines
5. Update documentation

## Risk Assessment

**Low Risk:**
[List low-risk changes]

**Medium Risk:**
[List items needing testing]

**High Risk:**
[List critical compatibility concerns]

4. Backup Current State

Before making changes:

bash

# Create backup branch if in git repo
git branch -c backup-before-bun-migration

# Or suggest user commits current state
git add -A
git commit -m "Backup before Bun migration"

5. Update package.json

Read current package.json:

typescript

// Read and parse package.json

Update scripts to use Bun:

json

{
  "scripts": {
    "dev": "bun run --hot src/index.ts",
    "start": "bun run src/index.ts",
    "build": "bun build src/index.ts --outdir=dist",
    "test": "bun test",
    "typecheck": "bun run --bun tsc --noEmit",
    "lint": "bun run --bun eslint ."
  }
}

Update engines field:

json

{
  "engines": {
    "bun": ">=1.0.0"
  }
}

For libraries, add exports field if not present:

json

{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

6. Update tsconfig.json

Read current tsconfig:

bash

cat tsconfig.json

Apply Bun-specific updates:

json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["bun-types"],
    "lib": ["ES2022"],
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noEmit": true
  }
}

Key changes explained:

•moduleResolution: "bundler" → Uses Bun's module resolution
•types: ["bun-types"] → Adds Bun's TypeScript definitions
•allowImportingTsExtensions: true → Allows importing .ts files directly
•noEmit: true → Bun runs TypeScript directly, no compilation needed

7. Handle Workspace Configuration

For monorepos with workspaces:

Verify workspace configuration is compatible:

json

{
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

Bun supports the same workspace syntax as npm/yarn/pnpm.

Check workspace dependencies:

bash

# Verify workspace structure
find . -name "package.json" -not -path "*/node_modules/*"

8. Install Dependencies with Bun

Remove old lockfiles:

bash

rm -f package-lock.json yarn.lock pnpm-lock.yaml

Install with Bun:

bash

bun install

This creates bun.lockb (Bun's binary lockfile).

For workspaces:

bash

bun install --frozen-lockfile  # Equivalent to npm ci

9. Update Test Configuration

If using Jest, migrate to Bun test:

Create bunfig.toml for test configuration:

toml

[test]
preload = ["./tests/setup.ts"]
coverage = true
coverageThreshold = 0.8

Update test files:

•Replace import { test, expect } from '@jest/globals'
•With import { test, expect } from 'bun:test'

Jest compatibility notes:

•Most Jest APIs work out of the box
•jest.mock() → Use mock() from bun:test
•Snapshot testing works the same
•Coverage reports may differ slightly

10. Update Environment Configuration

Check .env files:

bash

ls -la | grep .env

Bun loads .env files automatically (same as dotenv package).

Update environment loading code:

•Remove require('dotenv').config()
•Bun loads .env by default

11. Update Build Configuration

If using webpack/rollup/esbuild:

Consider replacing with Bun's built-in bundler:

typescript

// bun-build.ts
await Bun.build({
  entrypoints: ['./src/index.ts'],
  outdir: './dist',
  minify: true,
  splitting: true,
  sourcemap: 'external',
  target: 'bun',
});

Update build script in package.json:

json

{
  "scripts": {
    "build": "bun run bun-build.ts"
  }
}

12. Update CI/CD Configuration

GitHub Actions example:

yaml

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Run tests
        run: bun test

      - name: Type check
        run: bun run typecheck

      - name: Build
        run: bun run build

13. Verification Steps

Run these commands to verify migration:

bash

# 1. Check dependencies installed correctly
bun install

# 2. Run type checking
bun run --bun tsc --noEmit

# 3. Run tests
bun test

# 4. Try development server
bun run dev

# 5. Test production build
bun run build

14. Update Documentation

Create or update these documentation sections:

README.md:

markdown

## Prerequisites

- [Bun](https://bun.sh) 1.0 or higher

## Installation

```bash
bun install

Development

bash

bun run dev

Testing

bash

bun test

code


**CHANGELOG.md entry:**
```markdown
## [Version] - [Date]

### Changed
- Migrated from Node.js/npm to Bun
- Updated all dependencies to Bun-compatible versions
- Replaced [specific packages] with [alternatives]
- Updated TypeScript configuration for Bun

Common Migration Issues & Solutions

Issue: Native Module Incompatibility

Symptoms:

code

error: Cannot find module "bcrypt"

Solution:

bash

# Replace with pure JavaScript alternative
bun remove bcrypt
bun add bcryptjs

# Update imports
# Before: import bcrypt from 'bcrypt';
# After: import bcrypt from 'bcryptjs';

Issue: ESM/CommonJS Conflicts

Symptoms:

code

error: require() of ES Module not supported

Solution:

Add to package.json:

json

{
  "type": "module"
}

Or use .mts extension for ES modules and .cts for CommonJS.

Issue: Path Alias Resolution

Symptoms:

code

error: Cannot resolve "@/components"

Solution:

Verify tsconfig.json paths match:

json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Bun respects TypeScript path aliases automatically.

Issue: Test Failures

Symptoms:

code

error: jest is not defined

Solution:

Update test imports:

typescript

// Before
import { describe, it, expect } from '@jest/globals';

// After
import { describe, it, expect } from 'bun:test';

Migration Checklist

Present this checklist to the user:

Post-Migration Performance Verification

After migration, help user verify performance improvements:

bash

# Compare install times
time bun install  # Should be 3-10x faster than npm

# Compare test execution
time bun test     # Should be faster than Jest

# Compare startup time
time bun run src/index.ts  # Should be 90% faster than ts-node

Rollback Procedure

If migration encounters critical issues:

bash

# Return to backup branch
git checkout backup-before-bun-migration

# Or restore original state
git reset --hard HEAD~1

# Reinstall original dependencies
npm install  # or yarn/pnpm

Completion

Once migration is complete, provide summary:

•✅ Migration status (success/partial/issues)
•✅ List of changes made
•✅ Performance improvements observed
•✅ Any remaining manual steps
•✅ Links to Bun documentation for ongoing development