Node API mapping
Make verifiable choices among Node built-ins, Web APIs, and Deno APIs
Deno supports a broad set of node: APIs, so migration does not require rewriting every call. Start with compatibility APIs, then adopt Web or Deno APIs where they reduce dependencies or improve portability.
| Node.js | Deno / Web API | Guidance |
|---|---|---|
fs.promises.readFile(path, "utf8") | Deno.readTextFile(path) | both need file permission |
fs.promises.writeFile | Deno.writeTextFile | scope access to a directory |
http.createServer | Deno.serve | prefer Web Request/Response for new servers |
process.env.NAME | Deno.env.get("NAME") | grant only named variables |
process.argv.slice(2) | Deno.args | direct CLI equivalent |
child_process.spawn | new Deno.Command() | needs --allow-run=<cmd> |
__dirname | new URL(".", import.meta.url) | keep URL semantics, convert only if needed |
crypto.randomUUID() | crypto.randomUUID() | reuse the Web API |
Buffer | Uint8Array / TextEncoder | prefer Web types at protocol boundaries |
File-reading example
// Compatibility first: keep the Node API
import { readFile } from "node:fs/promises";
const a = await readFile("config.json", "utf8");
// Deno-first: use the shorter text API
const b = await Deno.readTextFile("config.json");
Both should run with the same least privilege:
deno run --allow-read=config.json main.ts
Migration tests should cover paths, encoding, stream backpressure, signals, timeouts, and error shapes. Similar names do not guarantee identical boundary behavior.