Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Concepts and Pitfalls

The node: prefix

Why you should import Node.js built-in modules with the node: prefix, which modules require it, how it prevents shadowing, and how to check for built-ins.

Every core module in Node.js can be loaded with a node: prefix: node:fs, node:path, node:http. The prefix is a URL scheme that says "this is a built-in module, not something from node_modules". It works in both import and require(), and it is the recommended style for all new code.

There are three reasons to use it: it makes built-ins instantly recognizable when reading code, it guarantees you get the real core module even if a package with the same name is installed, and a few newer core modules can only be loaded with the prefix.

NODE
import fs from 'node:fs';
import { test } from 'node:test';      // 'test' alone would not work

Try it

Node.js What counts as a built-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.

Node.js Errors for unknown names

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.

How the prefix behaves

  • It is a scheme, not a folder. node: forces resolution to the built-in module list; the node_modules lookup is skipped entirely.
  • Unknown names fail with a clear error. node:made-up throws ERR_UNKNOWN_BUILTIN_MODULE, while made-up becomes an ordinary package lookup and fails with ERR_MODULE_NOT_FOUND (or MODULE_NOT_FOUND for require()).
  • Unprefixed names still work for the long-standing core modules, so older code keeps running. Node will not remove that.
  • Prefix-only modules such as node:test, node:sqlite and node:sea cannot be loaded as test, sqlite or sea, since those names could clash with packages on npm. module.isBuiltin() and module.builtinModules reflect this.
  • Subpaths work the same: node:fs/promises, node:stream/web, node:test/reporters.
  • Bundlers and test tools generally understand the prefix. If an older tool does not, upgrading it is usually the fix.

Usage notes

  • Be consistent. Use the prefix everywhere in a project. A linter rule (unicorn/prefer-node-protocol or similar) can enforce it.
  • Shadowing risk is real. A dependency named fs, path or util on npm exists for historical reasons. Without the prefix, resolution rules still give you the built-in first, but the prefix removes any doubt for the reader.
  • It is also a signal for security review: a node: import cannot come from third-party code.
  • Mocking: the test runner's module mocks accept node: specifiers, so mock with the same string the code imports.
  • process.getBuiltinModule('node:fs') gives synchronous access to a built-in from either module type; see process.getBuiltinModule().
  • Browsers and edge runtimes that mimic Node often support the prefix too, which helps code move between environments.