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.
import fs from 'node:fs'; import { test } from 'node:test'; // 'test' alone would not work
Try it
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.
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; thenode_moduleslookup is skipped entirely. - Unknown names fail with a clear error.
node:made-upthrowsERR_UNKNOWN_BUILTIN_MODULE, whilemade-upbecomes an ordinary package lookup and fails withERR_MODULE_NOT_FOUND(orMODULE_NOT_FOUNDforrequire()). - 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:sqliteandnode:seacannot be loaded astest,sqliteorsea, since those names could clash with packages on npm.module.isBuiltin()andmodule.builtinModulesreflect 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-protocolor similar) can enforce it. - Shadowing risk is real. A dependency named
fs,pathorutilon 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; seeprocess.getBuiltinModule().- Browsers and edge runtimes that mimic Node often support the prefix too, which helps code move between environments.