npm compatibility

18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Deno runs npm packages directly without separate install

Because Deno runs npm packages directly, deno run -A npm:<tool> runs any npm tool without a separate npm install step. To save typing, add the command as a task in deno.json and run it with deno task.

npm to Deno CLI commands cheatsheet

Dependencies: npm install → deno install; npm install <pkg> → deno add <pkg>; npm install -D <pkg> → deno add -D <pkg>; npm uninstall <pkg> → deno remove <pkg>; npm update → deno update; npm outdated → deno outdated; npm ci → deno ci; npm audit → deno audit; npm explain <pkg> → deno why <pkg>. Run and execute: node file.js → deno file.js; npm run <script> → deno task <script>; npx <pkg> → dx <pkg>.

Use import map instead of package.json overrides

To pin a transitive dependency in Deno, use an import map entry in configuration rather than the overrides field in package.json.

npm workspaces field works directly in Deno

npm stores workspace globs in package.json under the workspaces field, and Deno reads that field directly. Members reference each other through the workspace: protocol in their package.json dependencies, exactly as they do under npm. There is nothing to convert.

deno task runs package.json scripts

Scripts defined in package.json run with deno task, the equivalent of npm run. Example: deno task start.

deno.lock seeded from package-lock.json on first install

On the first deno install, when there is no deno.lock yet, Deno seeds it from your existing package-lock.json. The exact versions and integrity hashes you already had pinned carry over, so you don't get a surprise round of upgrades. After that, Deno maintains deno.lock and leaves package-lock.json untouched.

Lifecycle scripts do not run by default in Deno

Lifecycle scripts like install or postinstall do not run by default in Deno. If a dependency relies on an install or postinstall script (native addons, node-gyp builds), allow it per package with deno install --allow-scripts=npm:<pkg>, or manage approvals with deno approve-scripts. This is a security default.

deno task runs package.json scripts

Scripts defined in package.json run with deno task, the equivalent of yarn run.

deno install reads package.json and creates node_modules

deno install reads your existing package.json and resolves the same npm packages as yarn install would. It writes a node_modules directory and a deno.lock lockfile.

deno install seeds lockfile from yarn.lock for Yarn v1

On first deno install when there is no deno.lock yet, Deno seeds the lockfile from a Yarn Classic (v1) yarn.lock, preserving the versions and integrity hashes already pinned. Yarn Berry (v2+) uses a different lockfile format that Deno does not seed from; in that case Deno resolves package.json ranges fresh.

Yarn to Deno CLI commands mapping

Yarn and Deno equivalents: 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 up <pkg> → deno update; yarn outdated → deno outdated; yarn install --immutable → deno ci; yarn npm audit → deno audit; yarn why <pkg> → deno why <pkg>; node file.js → deno file.js; yarn <script> → deno task <script>; yarn run <script> → deno task <script>; yarn dlx <pkg> → dx <pkg>.

Deno does not support Plug'n'Play

Deno does not implement Yarn's Plug'n'Play (PnP). When you run deno install, it writes a normal node_modules directory instead. The PnP-specific files .pnp.cjs and .pnp.loader.mjs are no longer used, and .yarnrc.yml resolver settings (nodeLinker, pnpMode, plugins) do not carry over to Deno.

yarn patch has no built-in Deno equivalent

yarn patch has no built-in Deno equivalent. To handle patched dependencies, either vendor the dependency or keep the patch in a fork.

JSR packages in package.json

JSR packages can be declared directly in `package.json` using the `jsr:` scheme, without needing a separate `deno.json`. This works with `deno install` and brings JSR packages to any project using `package.json` for dependency management.

overrides field in package.json

The `overrides` field in `package.json` controls transitive dependency versions throughout the dependency tree. This is useful for applying security patches, fixing version compatibility issues, or replacing packages. Global overrides apply to all packages using a dependency, while nested overrides (like `express: { qs: 6.13.0 }`) apply only to specific package contexts.

Publishing to npm with deno pack

deno pack (available in Deno 2.8 and later) builds an npm-compatible tarball from a Deno-first project by transpiling TypeScript, generating type declarations, and producing the package.json metadata npm expects. Run deno pack to create the tarball, then npm publish ./package.tgz to publish it.

dnt for advanced npm builds

dnt is the Deno-to-npm build tool used for older setups or builds that need fine-grained control over the output, such as shims, multiple targets, or test running during the build.

npm packages in Deno tests

Test helpers from npm keep working in Deno tests through npm: specifiers, for example npm:@testing-library/dom for DOM assertions. The test runner itself is the part being migrated from Jest to Deno.

Give your agent this brain