bun-doctor

library0.0.7jsnpmunverified

CLI tool to diagnose Node.js-to-Bun migration readiness for JavaScript/TypeScript projects. Current stable version 0.0.7 (pre-v1.0 beta). Scans package managers, lockfiles, tsconfig, GitHub Actions, dependency compatibility, and Bun-specific code risks. Outputs a 0-100 readiness score with grouped Blockers, Risks, Migration tasks, and Optional wins. Inspired by React Doctor, focuses on verifiable sources from Bun docs and Node compatibility table. No release cadence yet; single author project. Key differentiator: explicit migration scoring with actionable diagnostics, not just compatibility checks.

devops testing

npm install bun-doctor

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BUN-DOCTOR

bun-doctor

devopsjavascriptv0.0.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

runDiagnostics

✓ import { runDiagnostics } from 'bun-doctor'

✗ const runDiagnostics = require('bun-doctor').runDiagnostics

ESM-only since v0.0.1; does not support CommonJS require

default

✓ import bunDoctor from 'bun-doctor'

✗ const bunDoctor = require('bun-doctor')

Module provides named exports, not default export in CommonJS

type DiagnosticsOptions

✓ import type { DiagnosticsOptions } from 'bun-doctor'

✗ import { DiagnosticsOptions } from 'bun-doctor'

DiagnosticsOptions is a TypeScript type, use type-only import to avoid runtime import

Shows programmatic usage with runDiagnostics function and default CLI invocation.

// Run CLI on a project directory import { runDiagnostics } from 'bun-doctor'; const report = await runDiagnostics({ directory: process.argv[2] || '.', verbose: process.env.DEBUG === 'true', showWins: false, failOn: 'blocker' }); console.log(`Score: ${report.score}`); console.log('Blockers:', report.blockers.length); console.log('Risks:', report.risks.length); console.log('Migrations:', report.migrations.length); console.log('Wins:', report.wins.length); if (report.blockers.length > 0) { process.exit(1); } // Alternatively: npx -y bun-doctor@latest . --score

Debug

Known issues

breakingAPI changed from synchronous to async between v0.0.2 and v0.0.3; runDiagnostics now returns a Promise.

fix

Use await or .then() when calling runDiagnostics.

affects: >=0.0.3

breakingOutput format changed from array to structured object in v0.0.5; report.score, report.blockers, etc.

fix

Update code to access report properties directly instead of assuming array.

affects: >=0.0.5

deprecatedThe `--all` flag was renamed to `--verbose` in v0.0.6; `--all` still works but will be removed in v0.1.0.

fix

Use `--verbose` instead of `--all`.

affects: >=0.0.6 <1.0.0

gotchaScoring penalty values changed between v0.0.4 and v0.0.5: Blocker went from 10 to 12, Risk from 4 to 5, Migration from 1 to 2. This may break CI thresholds if you hardcoded expected scores.

fix

Update any hardcoded score expectations; use relative thresholds instead of absolute scores.

affects: >=0.0.5

gotchaThe package requires Node.js >=20; running on older Node versions throws ERR_REQUIRE_ESM.

fix

Upgrade Node.js to version 20 or later, or use npx with --node-option=--experimental-vm-modules (not recommended).

affects: >=0.0.1

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module /path/to/bun-doctor/index.js from /path/to/project/script.js not supported.

Using CommonJS require() to import an ESM-only package.

fix

Switch to ES modules: use import or set type: module in package.json.

Error: Cannot find module 'typescript'

TypeScript is missing from node_modules; bun-doctor attempts to load it for tsconfig parsing.

fix

Install TypeScript: npm install --save-dev typescript, or use --no-package flag to skip checks.

TypeError: runDiagnostics is not a function

Importing a named export that doesn't exist; likely caused by wrong import name or outdated package.

fix

Update bun-doctor to >=0.0.3 and use correct import: import { runDiagnostics } from 'bun-doctor'.

Error: Cannot read properties of undefined (reading 'score')

Accessing report.score before awaiting the promise from runDiagnostics.

fix

Add await: const report = await runDiagnostics(...);

Upgrade

Version history

0.0.7latest on npm

Audit

Dependencies

typescriptoptionaloptional peer dependency: used if project uses TypeScript for config/tsconfig parsing

Agent activity

25 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/kylegrahammatzen/bun-doctor ↗

packagebun-doctor ↗

homepagehttps://github.com/kylegrahammatzen/bun-doctor#readme ↗