Node.js Reference ยท Globals and Console
Node.js require() function
Reference for require() in Node.js: loading built-ins, files, JSON and packages, resolution order, require.cache, require.resolve and loading ES modules.
require() loads a module in CommonJS and returns whatever that module put on module.exports. It can load built-in modules (require('node:fs')), your own files (require('./util.js')), JSON files and packages from node_modules.
Loading is synchronous and cached: the first call runs the file, later calls return the same exported value. require is not a global; Node passes it as a parameter to the function that wraps each CommonJS file, so it does not exist in ES modules (create one with createRequire).
// cjs const path = require('node:path'); const config = require('./config.json');
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.
Syntax
require(id: string): any require.resolve(request: string, options?: { paths?: string[] }): string require.cache: Record<string, Module> require.main: Module | undefined
| Name | Description |
|---|---|
id |
A built-in name ('node:fs'), a relative or absolute path ('./a', '/app/a.js') or a package name ('lodash'). |
require.resolve() |
Returns the absolute filename require would load, without running it. |
require.cache |
Object keyed by absolute filename; deleting a key forces a fresh load next time. |
require.main |
The entry-point module; require.main === module tells you the file was run directly. |
Returns: the value of module.exports of the loaded module (a parsed value for .json).
Errors: MODULE_NOT_FOUND when nothing matches; ERR_REQUIRE_ESM or ERR_REQUIRE_ASYNC_MODULE when an ES module cannot be loaded synchronously; syntax errors in the target are thrown to the caller.
Usage notes
- Resolution order: built-in modules first, then relative/absolute paths (trying the exact name, then
.js,.json,.node, then a folder'spackage.jsonmainorindex.js), thennode_modulesfolders from the current directory upward. - Use the
node:prefix for built-ins. It makes the intent clear and cannot be shadowed by a package with the same name. - Caching means shared state. Two files that require the same module get the same object, which is what makes singletons work. It also means the module body runs only once.
- Circular requires return the partially filled
module.exportsof the file that is still loading. Move shared code to a third module to avoid surprises. - JSON files are parsed once and cached. Edits to the file are not seen until the cache entry is deleted.
- Loading ES modules: since Node 22.12 (and in Node 24)
require()can load an ES module that has no top-levelawait; one that does throwsERR_REQUIRE_ASYNC_MODULE. Useawait import()for those. - In ES modules use
import, orcreateRequire(import.meta.url)fromnode:moduleto get arequirefunction (useful for JSON and.nodeaddons). - Dynamic requires (
require(variable)) work but defeat bundlers and static analysis. Keep specifiers literal where you can.