Migrate To Deno

DenoOfficialCreated by denolandDistributed by Deno

Skill
Workflow
Software development
MIT
No issues found

From the author

Use when moving a Node.js, npm, Yarn, pnpm, or Bun project to Deno, or when adopting Deno incrementally in an existing JavaScript or TypeScript codebase. Covers using Deno as a drop-in package manager, running existing package.json scripts, CommonJS versus ESM, node_modules layout, lockfile migration, permissions, whether to adopt the built-in toolchain, and per-tool command equivalents.

— the description by denoland

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a phased approach to migrating existing JavaScript and TypeScript projects to Deno. It emphasizes that most Node.js projects can run on Deno without code changes by leveraging existing package.json files and node_modules support. The guide outlines a four-rung migration strategy: starting with Deno as a package manager, running the application, tightening security permissions, and optionally adopting Deno's built-in toolchain. It also includes comprehensive command mapping and guidance on handling specific migration challenges like CommonJS/ESM compatibility, lifecycle scripts, and dependency management.

What it does

Provides a step-by-step migration path from Node.js, npm, Yarn, pnpm, or Bun to Deno.
Maps common package manager and CLI commands to their Deno equivalents.
Explains how to handle CommonJS and ESM module resolution in Deno.
Details the process for managing permissions and security policies for existing applications.
Offers guidance on migrating lockfiles and maintaining compatibility with existing CI/CD pipelines.
Addresses specific migration hurdles like lifecycle scripts and node_modules layout differences.

When to use it

When you want to switch your project's runtime to Deno while keeping existing dependencies.
When you need to migrate an existing npm, Yarn, pnpm, or Bun project incrementally.
When you are unsure how to map your current development workflow commands to Deno.
When you need to troubleshoot common migration issues like permission errors or module resolution.

Advantages

Allows for incremental, reversible migration steps.
Supports existing package.json and node_modules structures.
Provides clear command-line parity for common development tasks.
Enables granular security controls via Deno's permission system.
Maintains compatibility with existing lockfiles during the transition.

Usage examples

“How do I start using Deno as a package manager for my existing npm project?”: You can run 'deno install' to read your package.json, resolve dependencies, and generate a 'deno.lock' file without affecting your current node_modules or npm workflow.
“What is the equivalent of 'npm run build' in Deno?”: You should use 'deno task build', which executes the 'build' script defined in your package.json.
“How do I handle 'ReferenceError: require is not defined' after switching to Deno?”: This indicates a CommonJS file is being treated as ESM. You should ensure your package.json contains 'type': 'commonjs' or rename the file extension to .cjs.
“How can I run my existing Node.js project in Deno safely?”: Start by using 'deno run -A' to confirm the application functions, then gradually replace '-A' with specific flags like '--allow-net' or '--allow-read' to enforce security.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/denoland/migrate-to-deno/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip migrate-to-deno.zip -d .agents/skills

Documentation by denoland

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.

Optional, and usually not worth it for an existing project. These are not drop-in replacements; parity is incomplete, so this is a real migration, not a config change. A project happy with prettier, eslint, and vitest should keep them and use Deno as runtime and package manager only. Prefer the built-in tools for new projects. If you do move an existing one, go a tool at a time.

Command equivalents

Task	npm	Yarn	pnpm	Bun	Deno
Install all	`npm install`	`yarn install`	`pnpm install`	`bun install`	`deno install`
Add	`npm i <p>`	`yarn add <p>`	`pnpm add <p>`	`bun add <p>`	`deno add <p>`
Add dev	`npm i -D <p>`	`yarn add -D <p>`	`pnpm add -D <p>`	`bun add -d <p>`	`deno add -D <p>`
Remove	`npm uninstall <p>`	`yarn remove <p>`	`pnpm remove <p>`	`bun remove <p>`	`deno remove <p>`
CI install	`npm ci`	`yarn install --immutable`†	`pnpm i --frozen-lockfile`	`bun install --frozen-lockfile`	`deno ci`
Run script	`npm run <s>`	`yarn <s>`	`pnpm <s>`	`bun run <s>`	`deno task <s>`
Run binary	`npx <p>`	`yarn dlx <p>`	`pnpm dlx <p>`	`bunx <p>`	`dx <p>`
Outdated	`npm outdated`	`yarn outdated`‡	`pnpm outdated`	`bun outdated`	`deno outdated`
Audit	`npm audit`	`yarn npm audit`†	`pnpm audit`	`bun audit`	`deno audit`
Why	`npm ls <p>`	`yarn why <p>`	`pnpm why <p>`	`bun why <p>`	`deno why <p>`
Run a file	`node f.js`			`bun f.ts`	`deno f.ts`
Run TS	`ts-node f.ts`			`bun f.ts`	`deno f.ts`
Watch	`nodemon f.js`			`bun --watch f.ts`	`deno watch f.ts`
Format	prettier			prettier	`deno fmt`
Lint	eslint				`deno lint`
Test	jest, vitest			`bun test`	`deno test`
Coverage	nyc, c8				`deno coverage`
Type-check	`tsc --noEmit`			`tsc`	`deno check`
Bundle binary	pkg, nexe			`bun build --compile`	`deno compile`

† Yarn Berry (v2+) spelling. Yarn Classic (v1) uses yarn install --frozen-lockfile and yarn audit.

‡ Yarn Classic only — Berry removed yarn outdated.

dx is a separate binary installed alongside Deno, and an alias for deno x. It does not appear in the top-level deno --help output. Like npx, it runs the package with the sandbox disabled.

The four things that actually break

`Requires net access to "..."` (or read, env, run)

Deno grants nothing by default. Add that specific permission, or -A while still establishing the program works at all.

`ReferenceError: require is not defined`

A file containing CommonJS is being parsed as ESM. .cjs is always CommonJS, .mjs always ESM; .js and .ts follow "type" in the nearest package.json. For a CommonJS project, set "type": "commonjs".

A dependency is broken, or `postinstall` never ran

Lifecycle scripts don't run by default. Native addons notice immediately. Approvals are recorded in the config file, so this is one-time:

deno approve-scripts                              # interactive picker
deno install --allow-scripts=npm:better-sqlite3   # or name them directly

A tool cannot find files inside `node_modules`

Deno's layout is pnpm-style: real files in node_modules/.deno/, exposed via symlinks. Tools assuming npm's flat hoisted tree need:

{ "nodeModulesLinker": "hoisted" }

What has no Deno equivalent

Say so rather than improvising a workaround that won't hold:

Yarn Plug'n'Play. Deno creates a real node_modules; .pnp.cjs is unused and .yarnrc.yml resolver settings don't transfer.
yarn patch / pnpm patched dependencies. Vendor or fork.
overrides / resolutions. Pin via an import map entry instead.
Registry and resolver tuning in .npmrc / .yarnrc.yml.
Bun build features — macros, HTMLRewriter, HTML entrypoints.

Per-tool details

references/FROM_NPM.md — lockfile seeding, node_modules layout, overrides
references/FROM_YARN.md — Plug'n'Play, Berry vs Classic, workspaces
references/FROM_PNPM.md — pnpm-workspace.yaml, catalog:, patches
references/FROM_BUN.md — Bun API translation, bunfig.toml
references/NODE_APIS.md — node: built-ins, DENO_COMPAT, CJS/ESM

Files

ATTRIBUTION.mdAdded by AutoGineer881 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md8.6 KiB
references/FROM_BUN.md4.2 KiB
references/FROM_NPM.md1.8 KiB
references/FROM_PNPM.md2.5 KiB
references/FROM_YARN.md2.8 KiB
references/NODE_APIS.md3.5 KiB

references/FROM_YARN.md

Migrating from Yarn

Yarn is a package manager, not a runtime, so the migration is configuration rather than code. Deno reads the existing package.json, installs the same dependencies, and runs the same scripts.

Commands

Yarn	Deno
`yarn install`	`deno install`
`yarn add <pkg>`	`deno add <pkg>`
`yarn add -D <pkg>`	`deno add -D <pkg>`
`yarn remove <pkg>`	`deno remove <pkg>`
`yarn <script>`	`deno task <script>`
`yarn dlx <pkg>`	`dx <pkg>`
`yarn why <pkg>`	`deno why <pkg>`
`yarn workspaces foreach`	`deno task --filter '*' <script>`

Classic (v1) and Berry (v2+) diverge on the rest, so the mapping is not uniform. Deno has one spelling regardless of which the project came from:

Task	Yarn Classic (v1)	Yarn Berry (v2+)	Deno
CI install	`yarn install --frozen-lockfile`	`yarn install --immutable`	`deno ci`
Outdated	`yarn outdated`	removed	`deno outdated`
Audit	`yarn audit`	`yarn npm audit`	`deno audit`

Plug'n'Play — the main incompatibility

Deno does not implement PnP; it creates a conventional node_modules.

.pnp.cjs and .pnp.loader.mjs become unused. Delete them once migrated.
.yarnrc.yml resolver settings (nodeLinker, pnpMode, registry mirrors) do not transfer.
yarn patch has no equivalent. Vendor the dependency or maintain a fork.

If the project relied on PnP's strictness to catch undeclared dependencies, Deno's isolated layout gives similar protection: real files in node_modules/.deno/, exposed through symlinks.

Lockfiles

Yarn Classic (v1) — yarn.lock seeds deno.lock, preserving pins.
Yarn Berry (v2+) — the lockfile format differs enough that Deno generates fresh resolutions. Diff the resulting versions before committing; this is the one step in a Yarn migration where dependency versions can move.

Workspaces

"workspaces": ["packages/*"] works unchanged; members reference each other through the workspace protocol with no conversion.

resolutions

resolutions is not supported. Pin through an import map entry instead:

{
  "imports": {
    "lodash": "npm:lodash@^4.17.21"
  }
}

Lifecycle scripts

Don't run by default. Approve per package with deno approve-scripts or deno install --allow-scripts=npm:<pkg>.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

denoland

Publisher

Deno (Official)

Distributed by

Deno

Source

denoland/skills · skills/migrate-to-deno · commit d5f6ace

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by denoland or Deno.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download migrate-to-deno.zip