# Migrate from Node.js to Deno

Deno 2 reads `package.json`, resolves npm packages, and runs a broad set of Node APIs. Migration should not begin by rewriting imports. It should begin by proving that the application still satisfies its tests and production constraints on another runtime.

## Four-stage route

<Cards>
  <Card title="1. Establish a baseline" description="Pin versions, keep the current install flow, and run side-effect-free scripts and tests." href="/en/docs/migration/from-node" />
  <Card title="2. Align packages and config" description="Understand package.json, deno.json, lockfiles, and node_modules modes." href="/en/docs/migration/packages-and-config" />
  <Card title="3. Map APIs deliberately" description="Keep working node: APIs and adopt Web or Deno APIs only where they help." href="/en/docs/migration/api-mapping" />
  <Card title="4. Resolve compatibility" description="Handle CommonJS, native addons, install scripts, permissions, and tests." href="/en/docs/migration/troubleshooting" />
</Cards>

## Acceptance at every stage

```bash
deno install
deno check src/main.ts
deno test
deno task start
```

Do not remove the old lockfile, runtime command, or deployment path until CI, developer machines, and the target production environment all pass. Change only one of runtime, package management, testing, framework, or deployment in a single migration step.

<Callout type="info" title="When to pause">
If a critical dependency only ships an incompatible Node-API binary, the system deeply depends on custom loaders, or no production regression suite exists, build evidence and isolation first. Do not rewrite stable business logic just to declare the migration complete.
</Callout>

Official references: [Migrate to Deno](https://docs.deno.com/runtime/migrate/) and [Node and npm compatibility](https://docs.deno.com/runtime/fundamentals/node/).