# Migrate from Node.js

> Find and rewrite Node.js APIs that have a Bun equivalent with bun n2b, and migrate a project with bun migrate

`bun n2b` scans a project for Node.js APIs that have a faster or simpler Bun equivalent, such as `fs.readFile` for `Bun.file().text()` or `child_process` for `Bun.spawn`, and can rewrite them. `bun migrate` moves a whole Node.js project to Bun.

```bash terminal icon="terminal"
bun n2b
```

Each finding has a rule, a severity, a message and, when one exists, the replacement code.

## Rewrite code

```bash terminal icon="terminal"
# apply the safe rewrites
bun n2b --fix

# also apply the rewrites that change behavior in edge cases
bun n2b --aggressive
```

## Reports

```bash terminal icon="terminal"
bun n2b --report=json > n2b.json
bun n2b --report=jsonl
```

`bun n2b` runs the embedded migration engine directly. Its reports remain separate from `bun lint` diagnostics.

## Migrate a project

`bun migrate` applies every n2b rewrite, converts pnpm workspaces, catalogs and overrides to `package.json`, removes the other lockfiles and runs `bun install`.

```bash terminal icon="terminal"
# print the migration plan and change nothing
bun migrate --dry-run

bun migrate
```

`bun migrate` is the same as `bun n2b migrate`.

## Embedded engine

n2b and its rule registry are linked into the `bun` binary. Scans and reports run in process without installing a package or launching a migration backend. `BUN_N2B` does not select another implementation. `--external-backend` is unsupported; after `--`, it is a literal scan path. Project migration can run `bun install` when applying dependency changes.

`bun n2b --help` lists every n2b command and flag.

`bun n2b` and `bun migrate` always select the native commands. Use `bun run n2b` or `bun run migrate` to run a project's scripts.