Use Deno in an existing Node.js project

Most Node.js projects run in Deno with no changes. Deno reads package.json, installs the same npm dependencies into node_modules, runs both CommonJS and ES modules, and executes your existing npm scripts. This tutorial takes a typical Node project and runs it with Deno, step by step.

Install dependencies from package.json Jump to heading

deno install is the equivalent of npm install: it reads your existing package.json and materializes a node_modules directory:

$ deno install
Initialize ms@2.1.3
Installed 1 package in 2ms

Dependencies:
+ npm:ms 2.1.3

No deno.json is required; package.json alone is enough. A deno.lock file is created to pin exact versions.

Run your npm scripts Jump to heading

deno task is the equivalent of npm run and reads the scripts from your package.json unchanged:

package.json

{
  "name": "my-node-app",
  "type": "module",
  "scripts": {
    "start": "node main.js"
  },
  "dependencies": {
    "ms": "^2.1.3"
  }
}

$ deno task start
Task start node main.js
172800000

Run the entrypoint with Deno Jump to heading

To use Deno as the runtime, point it at the same entrypoint:

$ deno run main.js
172800000

Note

Deno is secure by default: if your code reads files, opens sockets, or accesses environment variables, grant the access explicitly, e.g. deno run --allow-net --allow-env main.js, or start permissive with deno run -A main.js and tighten later.

Two compatibility rules cover almost everything else:

Node built-ins use the node: prefix: write import os from "node:os" rather than import os from "os". Node itself supports this prefix, so the change is backwards-compatible.
CommonJS and ES modules both work: .cjs and .mjs are unambiguous, and .js follows the "type" field of the nearest package.json. A require()-based project with "type": "commonjs" runs as-is.

Note

Deno assumes ES modules by default. A .js file is only treated as CommonJS when the nearest package.json declares "type": "commonjs", unlike Node, which assumes CommonJS when the field is missing. Add that one line to older projects that rely on the implicit default.

Replace tooling incrementally Jump to heading

You don't have to switch everything at once: Deno works fine as just a package manager or just a task runner. When you're ready, the built-in toolchain replaces several dev dependencies with zero configuration:

Node.js tooling	Deno
`npm install`	deno install
`npm run <script>`	deno task
`eslint`	deno lint
`prettier`	deno fmt
`jest` / `mocha`	deno test
`tsc --noEmit`	deno check

For module resolution details, the full command cheatsheet, and tsconfig migration, see the Migrate from Node.js guide.

Install dependencies from package.json Jump to heading#

Run your npm scripts Jump to heading#

Run the entrypoint with Deno Jump to heading#

Replace tooling incrementally Jump to heading#

Did you find what you needed?

Install dependencies from package.json Jump to heading

Run your npm scripts Jump to heading

Run the entrypoint with Deno Jump to heading

Replace tooling incrementally Jump to heading