migrate-to-deno

Migrating to Deno

Requires Deno 2.9 or later. For general Deno usage once migrated, see the deno skill.

Most Node projects already run under Deno

Deno reads an existing package.json, resolves the same npm packages, writes a real node_modules, runs the same scripts, and supports node: built-ins. TypeScript runs with no build step.

There is usually no code to change — only which binary you invoke. Don't start by rewriting imports to jsr:, swapping dependencies for Deno-specific ones, or restructuring directories. Proposing that is the most common way this goes wrong.

Migrate in rungs

Each rung is independently useful and reversible. Stop wherever suits the project; plenty of teams stop at rung 1.

Rung 1 — Deno as the package manager only

deno install

Reads package.json, resolves the same dependencies, writes node_modules, and creates deno.lock — seeded from any existing package-lock.json, yarn.lock, bun.lock, or pnpm lockfile, so pins and integrity hashes carry over instead of drifting.

The app still runs under node; teammates are unaffected. Commit deno.lock once verified. To back out: delete deno.lock and node_modules, then npm install.

Rung 2 — Run it with Deno

deno run -A main.js      # or: deno -A main.js
deno task build          # runs scripts.build from package.json

Use -A here. The goal is confirming the program works, not designing a permission policy — changing both at once makes failures ambiguous.

Rung 3 — Tighten permissions

Replace -A with the narrowest set that works: run it, read what it asks for, grant exactly that.

deno run --allow-net=api.example.com --allow-read=./config --allow-env=PORT main.js

This buys something Node cannot offer, and is worth doing before deploying.

Rung 4 — Optionally, adopt the built-in toolchain

deno fmt for prettier, deno lint for eslint, deno test for jest or vitest, deno check for tsc, deno watch for nodemon, deno compile for pkg.