Skip to content
Tutorials Center
My learning

Topics

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).

NODE
// cjs
const path = require('node:path');
const config = require('./config.json');

Try it

Node.js Built-ins, files and caching

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, cache clearing and ES modules

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

NODE
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's package.json main or index.js), then node_modules folders 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.exports of 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-level await; one that does throws ERR_REQUIRE_ASYNC_MODULE. Use await import() for those.
  • In ES modules use import, or createRequire(import.meta.url) from node:module to get a require function (useful for JSON and .node addons).
  • Dynamic requires (require(variable)) work but defeat bundlers and static analysis. Keep specifiers literal where you can.