bun-compat-check

Check your Node.js project's dependency compatibility with Bun runtime before migrating.

Scans your package.json, performs static analysis of Node.js API usage in each dependency, detects native addons, and generates a compatibility report.

Install

# npm
npm install -g bun-compat-check

# bun (of course)
bun add -g bun-compat-check

Or use without installing:

npx bun-compat-check
bunx bun-compat-check

Usage

# Check current directory
bun-compat-check

# Check a specific project
bun-compat-check ./my-project

# Exclude devDependencies
bun-compat-check --exclude-dev

# Include optionalDependencies
bun-compat-check --optional

# JSON output (for CI/CD pipelines)
bun-compat-check --json

# Verbose — show details for all packages
bun-compat-check -v

Example Output

🔍 Bun Compatibility Report
──────────────────────────────────────────────────

❌ INCOMPATIBLE  [email protected]
   Native addon detected (binding.gyp / node-gyp / N-API). Likely incompatible
   with Bun's JavaScriptCore engine.

❌ INCOMPATIBLE  [email protected]
   Uses unsupported Node.js APIs: trace_events
   ✗ node:trace_events (unsupported)

⚠️  PARTIAL  [email protected]
   Uses partially supported Node.js APIs: worker_threads, vm
   ~ node:worker_threads (partial)
   ~ node:vm (partial)

✅ OK  [email protected]
✅ OK  [email protected]
✅ OK  [email protected]

──────────────────────────────────────────────────
Summary: 6 packages scanned

  ❌  2 incompatible — will not work on Bun
  ⚠️  1 partial — uses partially supported APIs
  ✅  3 compatible

Migration readiness: 67%
  → Several packages need attention before migrating.

How It Works

1. Native Addon Detection — Scans installed node_modules for signals like binding.gyp, node-gyp scripts, and N-API usage that indicate V8-dependent native addons.

2. Node.js API Static Analysis — Scans .js/.mjs/.cjs files in each package for require() and import of Node.js built-in modules, then cross-references against Bun's compatibility table to flag unsupported or partially supported APIs. The compatibility table is maintained in src/node-compat.ts (last verified: 2026-04-02).

3. Migration Score — Calculates a readiness percentage based on the ratio of non-incompatible packages (excludes packages that couldn't be analyzed).

Status Labels

| Icon | Status | Meaning | |------|--------|---------| | ✅ | Compatible | No incompatible Node.js API usage detected | | ⚠️ | Partial | Uses Node.js APIs with partial Bun support | | ❌ | Incompatible | Native addon or uses unsupported Node.js APIs | | ❓ | Unknown | Could not analyze (e.g. node_modules missing) |

CI/CD Integration

Use --json output and the exit code for automated checks:

# Exit code 1 if any incompatible packages found
bun-compat-check --json > compat-report.json || echo "Incompatible packages detected"

Contributing

Contributions welcome! The most impactful ways to help:

• Update the Node.js API compatibility table as Bun releases new versions (src/node-compat.ts)
• Improve static analysis accuracy (src/analyzer.ts)
• Report false positives/negatives via GitHub Issues

Support

If you find this tool useful, consider supporting the project:

• GitHub Sponsors
• Ko-fi

License

MIT