Node and npm support

Modern Node.js projects will run in Deno with little to no reworking required. However, there are some key differences between the two runtimes that you can take advantage of to make your code simpler and smaller when migrating your Node.js projects to Deno.

Explore built-in Node APIs

Using Node's built-in modules Jump to heading#

Deno provides a compatibility layer that allows the use of Node.js built-in APIs within Deno programs. However, in order to use them, you will need to add the node: specifier to any import statements that use them:

import * as os from "node:os";
console.log(os.cpus());

And run it with deno run main.mjs - you will notice you get the same output as running the program in Node.js.

Updating any imports in your application to use node: specifiers should enable any code using Node built-ins to function as it did in Node.js.

To make updating existing code easier, Deno will provide helpful hints for imports that don't use node: prefix:

import * as os from "os";
console.log(os.cpus());

$ deno run main.mjs
error: Relative import path "os" not prefixed with / or ./ or ../
  hint: If you want to use a built-in Node module, add a "node:" prefix (ex. "node:os").
    at file:///main.mjs:1:21

The same hints and additional quick-fixes are provided by the Deno LSP in your editor.

Using npm packages Jump to heading#

Deno has native support for importing npm packages by using npm: specifiers. For example:

import * as emoji from "npm:node-emoji";

console.log(emoji.emojify(`:sauropod: :heart:  npm`));

Can be run with:

$ deno run main.js
🦕 ❤️ npm

No npm install is necessary before the deno run command and no node_modules folder is created. These packages are also subject to the same permissions as other code in Deno.

npm specifiers have the following format:

npm:[@][/]

For examples with popular libraries, please refer to the tutorial section.

CommonJS support Jump to heading#

CommonJS is a module system that predates ES modules. While we firmly believe that ES modules are the future of JavaScript, there are millions of npm libraries that are written in CommonJS and Deno offers full support for them. Deno will automatically determine if a package is using CommonJS and make it work seamlessly when imported:

import react from "npm:react";
console.log(react);

$ deno run -E main.js
18.3.1

npm:react is a CommonJS package. Deno allows you to import it as if it were an ES module.

Deno strongly encourages the use of ES modules in your code but offers CommonJS support with following restrictions:

Deno's permission system is still in effect when using CommonJS modules. It may be necessary to provide at least --allow-read permission as Deno will probe the file system for package.json files and node_modules directory to properly resolve CommonJS modules.

Use .cjs extension Jump to heading#

If the file extension is .cjs Deno will treat this module as CommonJS.

const express = require("express");

Deno does not look for package.json files and type option to determine if the file is CommonJS or ESM.

When using CommonJS, Deno expects that dependencies will be installed manually and a node_modules directory will be present. It's best to set "nodeModulesDir": "auto" in your deno.json to ensure that.

$ cat deno.json
{
  "nodeModulesDir": "auto"
}

$ deno install npm:express
Add npm:express@5.0.0

$ deno run -R -E main.cjs
[Function: createApplication] {
  application: {
    init: [Function: init],
    defaultConfiguration: [Function: defaultConfiguration],
    ...
  }
}

-R and -E flags are used to allow permissions to read files and environment variables.

package.json type option Jump to heading#

Deno will attempt to load .js, .jsx, .ts, and .tsx files as CommonJS if there's a package.json file with "type": "commonjs" option next to the file, or up in the directory tree when in a project with a package.json file.

{
  "type": "commonjs"
}

const express = require("express");

Tools like Next.js's bundler and others will generate a package.json file like that automatically.

If you have an existing project that uses CommonJS modules, you can make it work with both Node.js and Deno, by adding "type": "commonjs" option to the package.json file.

Always detecting if a file might be CommonJS Jump to heading#

Telling Deno to analyze modules as possibly being CommonJS is possible by running with the --unstable-detect-cjs in Deno >= 2.1.2. This will take effect, except when there's a package.json file with { "type": "module" }.

Looking for package.json files on the file system and analyzing a module to detect if its CommonJS takes longer than not doing it. For this reason and to discourage the use of CommonJS, Deno does not do this behavior by default.

Create require() manually Jump to heading#

An alternative option is to create an instance of the require() function manually:

import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const express = require("express");

In this scenario the same requirements apply, as when running .cjs files - dependencies need to be installed manually and appropriate permission flags given.

require(ESM) Jump to heading#

Deno's require() implementation supports requiring ES modules.

This works the same as in Node.js, where you can only require() ES modules that don't have Top-Level Await in their module graph - or in other words you can only require() ES modules that are "synchronous".

export function greet(name) {
  return `Hello ${name}`;
}

import { greet } from "./greet.js";

export { greet };

const esm = require("./esm");
console.log(esm);
console.log(esm.greet("Deno"));

$ deno run -R main.cjs
[Module: null prototype] { greet: [Function: greet] }
Hello Deno

Import CommonJS modules Jump to heading#

You can also import CommonJS files in ES modules.

module.exports = {
  hello: "world",
};

import greet from "./greet.js";
console.log(greet);

$ deno run main.js
{
  "hello": "world"
}

Hints and suggestions

Deno will provide useful hints and suggestions to guide you towards working code when working with CommonJS modules.

As an example, if you try to run a CommonJS module that doesn't have .cjs extension or doesn't have a package.json with { "type": "commonjs" } you might see this:

module.exports = {
  hello: "world",
};

$ deno run main.js
error: Uncaught (in promise) ReferenceError: module is not defined
module.exports = {
^
    at file:///main.js:1:1

    info: Deno supports CommonJS modules in .cjs files, or when the closest
          package.json has a "type": "commonjs" option.
    hint: Rewrite this module to ESM,
          or change the file extension to .cjs,
          or add package.json next to the file with "type": "commonjs" option,
          or pass --unstable-detect-cjs flag to detect CommonJS when loading.
    docs: https://docs.deno.com/go/commonjs

Importing types Jump to heading#

Many npm packages ship with types, you can import these and use them with types directly:

import chalk from "npm:chalk@5";

Some packages do not ship with types but you can specify their types with the @ts-types directive. For example, using a @types package:

// @ts-types="npm:@types/express@^4.17"
import express from "npm:express@^4.17";

Module resolution

The official TypeScript compiler tsc supports different moduleResolution settings. Deno only supports the modern node16 resolution. Unfortunately many npm packages fail to correctly provide types under node16 module resolution, which can result in deno check reporting type errors, that tsc does not report.

If a default export from an npm: import appears to have a wrong type (with the right type seemingly being available under the .default property), it's most likely that the package provides wrong types under node16 module resolution for imports from ESM. You can verify this by checking if the error also occurs with tsc --module node16 and "type": "module" in package.json or by consulting the Are the types wrong? website (particularly the "node16 from ESM" row).

If you want to use a package that doesn't support TypeScript's node16 module resolution, you can:

1. Open an issue at the issue tracker of the package about the problem. (And perhaps contribute a fix 😃 (Although, unfortunately, there is a lack of tooling for packages to support both ESM and CJS, since default exports require different syntaxes. See also microsoft/TypeScript#54593)
2. Use a CDN, that rebuilds the packages for Deno support, instead of an npm: identifier.
3. Ignore the type errors you get in your code base with // @ts-expect-error or // @ts-ignore.

Including Node types Jump to heading#

Node ships with many built-in types like Buffer that might be referenced in an npm package's types. To load these you must add a types reference directive to the @types/node package:

/// <reference types="npm:@types/node" />

Note that it is fine to not specify a version for this in most cases because Deno will try to keep it in sync with its internal Node code, but you can always override the version used if necessary.

Executable npm scripts Jump to heading#

npm packages with bin entries can be executed from the command line without an npm install using a specifier in the following format:

npm:[@][/]

For example:

$ deno run --allow-read npm:cowsay@1.5.0 "Hello there!"
 ______________
< Hello there! >
 --------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

$ deno run --allow-read npm:cowsay@1.5.0/cowthink "What to eat?"
 ______________
( What to eat? )
 --------------
        o   ^__^
         o  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

node_modules Jump to heading#

When you run npm install, npm creates a node_modules directory in your project which houses the dependencies as specified in the package.json file.

Deno uses npm specifiers to resolve npm packages to a central global npm cache, instead of using a node_modules folder in your projects. This is ideal since it uses less space and keeps your project directory clean.

There may however be cases where you need a local node_modules directory in your Deno project, even if you don’t have a package.json (eg. when using frameworks like Next.js or Svelte or when depending on npm packages that use Node-API).

Default Deno dependencies behavior Jump to heading#

By default, Deno will not create a node_modules directory when you use the deno run command, dependencies will be installed into the global cache. This is the recommended setup for new Deno projects.

Automatic node_modules creation Jump to heading#

If you need a node_modules directory in your project, you can use the --node-modules-dir flag or nodeModulesDir: auto option in the config file to tell Deno to create a node_modules directory in the current working directory:

deno run --node-modules-dir=auto main.ts

or with a configuration file:

{
  "nodeModulesDir": "auto"
}

The auto mode automatically installs dependencies into the global cache and creates a local node_modules directory in the project root. This is recommended for projects that have npm dependencies that rely on node_modules directory - mostly projects using bundlers or ones that have npm dependencies with postinstall scripts.

Manual node_modules creation Jump to heading#

If your project has a package.json file, you can use the manual mode, which requires an installation step to create your node_modules directory:

deno install
deno run --node-modules-dir=manual main.ts

or with a configuration file:

{ "nodeModulesDir": "manual" }

You would then run deno install/npm install/pnpm install or any other package manager to create the node_modules directory.

Manual mode is the default mode for projects using a package.json. You may recognize this workflow from Node.js projects. It is recommended for projects using frameworks like Next.js, Remix, Svelte, Qwik etc, or tools like Vite, Parcel or Rollup.

node_modules with Deno 1.X Jump to heading#

Use the --node-modules-dir flag.

For example, given main.ts:

import chalk from "npm:chalk@5";

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

deno run --node-modules-dir main.ts

Running the above command, with a --node-modules-dir flag, will create a node_modules folder in the current directory with a similar folder structure to npm.

Node.js global objects Jump to heading#

In Node.js, there are a number of global objects available in the scope of all programs that are specific to Node.js, eg. process object.

Here are a few globals that you might encounter in the wild and how to use them in Deno:

• process - Deno provides the process global, which is by far the most popular global used in popular npm packages. It is available to all code. However, Deno will guide you towards importing it explicitly from node:process module by providing lint warnings and quick-fixes:

console.log(process.versions.deno);

$ deno run process.js
2.0.0
$ deno lint process.js
error[no-process-globals]: NodeJS process global is discouraged in Deno
 --> /process.js:1:13
  |
1 | console.log(process.versions.deno);
  |             ^^^^^^^
  = hint: Add `import process from "node:process";`

  docs: https://docs.deno.com/lint/rules/no-process-globals


Found 1 problem (1 fixable via --fix)
Checked 1 file

• require() - see CommonJS support

• Buffer - to use Buffer API it needs to be explicitly imported from the node:buffer module:

import { Buffer } from "node:buffer";

const buf = new Buffer(5, "0");

Prefer using Uint8Array or other TypedArray subclasses instead.

• __filename - use import.meta.filename instead.

• __dirname - use import.meta.dirname instead.

Node-API addons Jump to heading#

Deno supports Node-API addons that are used by popular npm packages like esbuild, npm:sqlite3 or npm:duckdb.

You can expect all packages that use public and documented Node-APIs to work.

As of Deno 2.0, npm packages using Node-API addons are only supported when a node_modules/ directory is present. Add "nodeModulesDir": "auto" or "nodeModulesDir": "manual" setting your deno.json file, or run with --node-modules-dir=auto|manual flag to ensure these packages work correctly. In case of misconfiguration Deno will provide hints how the situation can be resolved.

Migrating from Node to Deno Jump to heading#

Running your Node.js project with Deno is a straightforward process. In most cases you can expect little to no changes to be required, if your project is written using ES modules.

Main points to be aware of, include:

1. Importing Node.js built-in modules requires the node: specifier:

// ❌
import * as fs from "fs";
import * as http from "http";

// ✅
import * as fs from "node:fs";
import * as http from "node:http";

2. Some globals available in Node.js need to be explicitly imported, eg. Buffer:

import { Buffer } from "node:buffer";

3. require() is only available in files with .cjs extension, in other files an instance of require() needs to be created manually. npm dependencies can use require() regardless of file extension.

Running scripts Jump to heading#

Deno supports running npm scripts natively with the deno task subcommand (If you're migrating from Node.js, this is similar to the npm run script command). Consider the following Node.js project with a script called start inside its package.json:

{
  "name": "my-project",
  "scripts": {
    "start": "eslint"
  }
}

You can execute this script with Deno by running:

deno task start

Optional improvements Jump to heading#

One of Deno's core strengths is a unified toolchain that comes with support for TypeScript out of the box, and tools like a linter, formatter and a test runner. Switching to Deno allows you to simplify your toolchain and reduces the number of moving components in your project.

Configuration

Deno has its own config file, deno.json or deno.jsonc, which can be used to configure your project

You can use it to define dependencies using the imports option - you can migrate your dependencies one-by-one from package.json, or elect to not define them in the config file at all and use npm: specifiers inline in your code.

In addition to specifying dependencies you can use deno.json to define tasks, lint and format options, path mappings, and other runtime configurations.

Linting

Deno ships with a built-in linter that is written with performance in mind. It's similar to ESlint, though with a limited number of rules. If you don't rely on ESLint plugins, you can drop eslint dependency from devDependencies section of package.json and use deno lint instead.

Deno can lint large projects in just a few milliseconds. You can try it out on your project by running:

deno lint

This will lint all files in your project. When the linter detects a problem, it will show the line in your editor and in the terminal output. An example of what that might look like:

error[no-constant-condition]: Use of a constant expressions as conditions is not allowed.
 --> /my-project/bar.ts:1:5
  | 
1 | if (true) {
  |     ^^^^
  = hint: Remove the constant expression

  docs: https://docs.deno.com/lint/rules/no-constant-condition


Found 1 problem
Checked 4 files

Many linting issues can be fixed automatically by passing the --fix flag:

deno lint --fix

A full list of all supported linting rules can be found on https://docs.deno.com/lint/. To learn more about how to configure the linter, check out the deno lint subcommand.

Formatting

Deno ships with a built-in formatter that can optionally format your code according to the Deno style guide. Instead of adding prettier to your devDependencies you can instead use Deno's built-in zero-config code formatter deno fmt.

You can run the formatter on your project by running:

deno fmt

If using deno fmt in CI, you can pass the --check argument to make the formatter exit with an error when it detects improperly formatted code.

deno fmt --check

The formatting rules can be configured in your deno.json file. To learn more about how to configure the formatter, check out the deno fmt subcommand.

Testing

Deno encourages writing tests for your code, and provides a built-in test runner to make it easy to write and run tests. The test runner is tightly integrated into Deno, so that you don't have to do any additional configuration to make TypeScript or other features work.

Deno.test("my test", () => {
  // Your test code here
});

deno test

When passing the --watch flag, the test runner will automatically reload when any of the imported modules change.

To learn more about the test runner and how to configure it, check out the deno test subcommand documentation.

Private registries Jump to heading#

Deno supports private registries, which allow you to host and share your own modules. This is useful for organizations that want to keep their code private or for individuals who want to share their code with a select group of people.

What are private registries? Jump to heading#

Large organizations often host their own private npm registries to manage internal packages securely. These private registries serve as repositories where organizations can publish and store their proprietary or custom packages. Unlike public npm registries, private registries are accessible only to authorized users within the organization.

How to use private registries with Deno Jump to heading#

First, configure your .npmrc file to point to your private registry. The .npmrc file must be in the project root or $HOME directory. Add the following to your .npmrc file:

@mycompany:registry=http://mycompany.com:8111/
//mycompany.com:8111/:_auth=secretToken

Replace http://mycompany.com:8111/ with the actual URL of your private registry and secretToken with your authentication token.

Then update Your deno.json or package.json to specify the import path for your private package. For example:

{
  "imports": {
    "@mycompany/package": "npm:@mycompany/package@1.0.0"
  }
}

or if you're using a package.json:

{
  "dependencies": {
    "@mycompany/package": "1.0.0"
  }
}

Now you can import your private package in your Deno code:

import { hello } from "@mycompany/package";

console.log(hello());

and run it using the deno run command:

deno run main.ts

Node to Deno Cheatsheet Jump to heading#

¹ Type checking happens automatically, TypeScript compiler is built into the deno binary.