Migrating from Node.js to Deno

To migrate an existing Node.js program to Deno, there are a number of differences to take into account between the Node and Deno runtimes. This guide will attempt to call out several of those differences, and describe how you can begin to migrate your Node.js project to work on Deno.

Module imports and exports Jump to heading#

Deno supports ECMAScript modules exclusively, rather than a combination of ESM and CommonJS, as found in Node. If your Node.js code uses require, you should update it to use import statements instead. If your internal code uses CommonJS-style exports, those will need to be changed as well.

Consider the following two files in a Node.js program, located in the same directory:

const addNumbers = require("./add_numbers");
console.log(addNumbers(2, 2));

module.exports = function addNumbers(num1, num2) {
  return num1 + num2;
};

Running node index.js with the files above works fine in Node.js 20 and earlier. However, this code will not run unchanged if you attempt to use deno run index.js instead. You will need to change both the code that is consuming the module, and how you export functionality from the add_numbers module.

Replace require with import Jump to heading#

Replace require statements with an import, like so:

import addNumbers from "./add_numbers.js";

This statement uses the ES6 module standard, but does pretty much the same thing. Also, note that we include the full file extension when importing modules, much as you would in the browser. There is also no special handling of files named index.js.

Replace module.exports with export default Jump to heading#

In the add_numbers.js file that exports the function, we would use a default export from ES6 modules rather than the module.exports provided by CommonJS.

export default function addNumbers(num1, num2) {
  return num1 + num2;
}

After making those two changes, this code would run successfully with deno run index.js. Learn more about ES modules in Deno here.

Node.js built-ins Jump to heading#

In Node.js 20 and earlier, built-in modules in the Node.js standard library could be imported with "bare specifiers". Consider the Node program below with a .mjs extension:

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

The os module is built in to the Node.js runtime, and can be imported using a bare specifier as above.

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.

For example - if you update the code above to be this instead:

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

And run it with deno run index.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.

Runtime permissions in Deno Jump to heading#

Deno features runtime security by default, meaning that you as the developer must opt in to giving your code access to the filesystem, network, system environment, and more. Doing this prevents supply chain attacks and other potential vulnerabilities in your code. By comparison, Node.js has no concept of runtime security, with all code executed with the same level of permission as the user running the code.

Running your code with only the necessary flags Jump to heading#

When you run a Node.js project ported to Deno for the first time, the runtime will likely prompt you for access to the permissions it needs to execute your code. Consider the following simple express server:

import express from "npm:express@4";

const app = express();

app.get("/", function (_req, res) {
  res.send("hello");
});

app.listen(3000, () => {
  console.log("Express listening on :3000");
});

If you run it with deno run server.js, it would prompt you for a number of permissions required to execute the code and its dependencies. These prompts can show you what runtime permission flags need to be passed in to grant the access you need. Running the code above with the necessary permissions provided would look like this:

deno run --allow-net --allow-read --allow-env server.js

Reusing runtime flag configuration with deno task Jump to heading#

A common pattern for configuring a set of runtime flags is to set up scripts to be run with deno task. The following deno.json file has a task called dev which will run the express server from above with all the necessary flags.

{
  "tasks": {
    "dev": "deno run --allow-net --allow-read --allow-env server.js"
  }
}

You can then run the task with deno task dev.

Running with all permissions enabled Jump to heading#

It is possible, but not recommended in production or sensitive environments, to run your programs with all runtime permissions enabled. This would be the default behavior of Node, which lacks a permission system. To run a program with all permissions enabled, you can do so with:

deno run -A server.js

Running scripts from package.json Jump to heading#

Many Node.js projects make use of npm scripts to drive local development. In Deno, you can continue to use your existing npm scripts while migrating over time to deno task.

Running npm scripts in Deno Jump to heading#

One of the ways Deno supports existing package.json files is by executing any scripts configured there with deno task. Consider the following Node.js project with a package.json and a script configured within it.

console.log("running my task...");

{
  "name": "test",
  "scripts": {
    "start": "node bin/my_task.mjs"
  }
}

You can execute this script with Deno by running deno task start.

Using and managing npm dependencies Jump to heading#

Deno supports managing npm dependencies through a package.json file. Note that unlike using npm at the command line, you can simply run your project with deno run, and the first time your script runs, Deno will cache all the necessary dependencies for your application.

Going forward, we'd recommend that you manage dependencies through deno.json instead, which supports other types of imports as well.

When importing npm packages, you would use the npm: specifier, much like you would the node: specifier for any built-in Node modules.

import express from "npm:express@4";

const app = express();

app.get("/", function (_req, res) {
  res.send("hello");
});

app.listen(3000, () => {
  console.log("Express listening on :3000");
});

Node.js global objects Jump to heading#

In Node.js, there are a number of global objects that are available in the scope of all programs, like the process object or __dirname and __filename.

Deno does not add additional objects and variables to the global scope, other than the Deno namespace. Any API that doesn't exist as a web standard browser API will be found in this namespace.

The equivalent Deno expression for every Node.js built-in global object will vary, but it should be possible to accomplish everything you can do in Node using a slightly different method in Deno. For example, the process.cwd() function in Node.js exists in Deno as Deno.cwd().

__filename and __dirname Jump to heading#

Two very common Node.js global variables in CommonJS modules are __filename and __dirname. These globals are not supported in ECMAScript modules in Deno or Node.js, but there is still a way to get the same information in Deno Runtime APIs:

const __filename = import.meta.filename;
const __dirname = import.meta.dirname;