Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Deploy and Interop

npm Packages and Node.js Compatibility in Deno

Use the npm ecosystem from Deno with npm: specifiers, package.json and node_modules, the node: built-in modules, CommonJS interop, lifecycle scripts, and a plan for migrating a Node.js project.

Deno started as a rethink of Node.js, but today you do not have to choose one world. Deno 2 runs most npm packages, understands package.json, provides the node: built-in modules, and can run many Node.js projects with few changes. That means you get Deno's security model, built-in tooling and TypeScript support and access to the millions of packages on npm.

This lesson shows the three ways to use npm code, what compatibility covers, the known differences, and how to migrate an existing Node project step by step.

Deno is not available in the editor, so commands and npm: imports are read-only. The runnable blocks use Node 24, whose node: modules behave the same in Deno, plus a specifier parser that shows how npm: names are read.

Way 1: npm: specifiers

Put npm: in front of a package name and Deno downloads, caches and runs it. No npm install, no node_modules folder is needed by default:

TypeScript
import chalk from "npm:chalk@5";
import { z } from "npm:zod@^3.23";
import express from "npm:express@4";

console.log(chalk.green("works"));

const app = express();
app.get("/", (_req, res) => res.send("hello from express on Deno"));
app.listen(3000);
Terminal
deno run --allow-net --allow-env --allow-read main.ts

The general form is npm:<name>[@<version-range>][/<subpath>]:

Specifier Means
npm:chalk latest matching the lockfile or latest
npm:chalk@5 any 5.x
npm:@scope/pkg@^1.2.0 scoped package, semver range
npm:lodash-es@4/debounce.js a file inside the package

The stand-in below parses specifiers the way Deno reads them, so you can see each piece.

Node.js Reading npm: specifiers (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In a real project you give packages short names with the import map, so the version lives in one place:

Terminal
deno add npm:chalk@5 npm:zod
TypeScript
import chalk from "chalk";     // resolved through deno.json "imports"

Way 2: package.json and node_modules

If a project already has a package.json, Deno reads its dependencies, devDependencies and scripts:

Terminal
deno install                 # install everything from package.json (creates node_modules)
deno install npm:express     # add a package
deno task start              # runs "scripts" from package.json too
deno run main.js             # bare imports like "express" now resolve

You may see a node_modules folder. Deno creates one when package.json exists, or when you set "nodeModulesDir": "auto" or "manual" in deno.json. It is useful for tools that expect the folder (bundlers, some frameworks, editors). Without a package.json, Deno keeps packages in a global cache instead.

Two safety defaults differ from npm:

  • Lifecycle scripts (postinstall and friends) do not run unless you allow them: deno install --allow-scripts=npm:sharp,npm:esbuild. A package cannot run arbitrary code just by being installed.
  • Packages run inside the permission sandbox. An npm package that tries to read your disk or open a socket needs --allow-read or --allow-net like any other code, so a malicious dependency is limited by what you allowed.

Way 3: the node: built-in modules

Deno implements the Node standard library under the node: prefix: node:fs, node:path, node:crypto, node:events, node:stream, node:http, node:child_process, node:worker_threads, node:sqlite and many more. Always write the prefix, because Deno requires it in ES modules:

TypeScript
import { join } from "node:path";
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import process from "node:process";

Because they are the same modules, code that uses them runs the same everywhere. This example is plain Node code that works unchanged in Deno:

Node.js node: built-ins that behave the same in Deno

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In new Deno code prefer the web-standard equivalents where they exist (fetch, crypto.subtle, Uint8Array with TextEncoder, URL, Deno.readTextFile). They are portable to browsers and edge runtimes. Use node: modules when an npm package needs them or when no web API fits.

CommonJS and the process global

Deno is ES-modules-first. It runs CommonJS (require, module.exports) in files ending in .cjs, or in .js files when the nearest package.json says "type": "commonjs". In ESM you can create a require when you need one:

TypeScript
import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const legacy = require("legacy-package");

Many Node globals are available for compatibility: process, Buffer, global, __dirname and __filename only inside CommonJS. In ESM use import.meta.dirname and import.meta.filename instead:

TypeScript
const config = await Deno.readTextFile(`${import.meta.dirname}/config.json`);

What to watch out for

Topic Note
Native addons (.node files) many work through Node-API; some old ones do not
child_process and worker_threads supported, and need --allow-run / follow worker rules
Permissions npm code gets only what you grant; expect to add --allow-read, --allow-env, --allow-net
Unstable corners rarely used Node APIs may be partly implemented; test your actual code paths
Types most packages ship their own; otherwise add @types/... or // @deno-types hints
node_modules layout tools that look for hoisted packages need "nodeModulesDir": "manual"

Migrating a Node project

  1. Run deno install in the project and then deno task <your script>; many projects just work.
  2. Add the node: prefix to built-in imports (fs becomes node:fs).
  3. Add missing file extensions to relative imports (./utils becomes ./utils.ts).
  4. Run with --allow-all first to get it working, then replace it with the minimal flags (deno run will tell you what is missing).
  5. Replace tools gradually: deno test for Jest, deno fmt for Prettier, deno lint for ESLint, deno check for tsc.
  6. Keep package.json if you need both runtimes. You can run the same app in Node and Deno during the transition.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does import chalk from "npm:chalk@5" do?

    The npm: scheme makes Deno fetch, cache and run the package with no separate install step.
  2. 2. By default, do npm postinstall scripts run when you run deno install?

    Deno blocks lifecycle scripts unless you list the packages that may run them.
  3. 3. How do you get the folder of the current ES module in Deno?

    __dirname exists only in CommonJS. In ES modules use import.meta.dirname (or import.meta.url).
  4. 4. Why does an npm package still need --allow-net to open a socket?

    Permissions apply to the whole process, including dependencies, which limits what a compromised package can do.

Summary

  • Use npm in three ways: npm: specifiers, package.json with deno install, and node: built-ins.
  • Manage versions through the import map (deno add npm:...) and the lockfile.
  • Lifecycle scripts are off by default; permissions limit every dependency.
  • Prefer web-standard APIs in new code; use node: where a package or API requires it.
  • Migrate gradually: install, add prefixes and extensions, tighten permissions, then swap tools.

Next: Publishing to JSR