Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js --require and --import flags

Reference for the node --require (-r) and --import flags: preloading CommonJS and ES modules before your program, execution order, and typical uses.

--require (short form -r) and --import tell Node.js to load one or more modules before your main entry point runs. The preloaded code can set up instrumentation, polyfills, environment variables, error handlers or module customization hooks, and your program does not need to know about it.

--require loads a CommonJS module with require(). --import loads a module with import(), so it accepts ES modules (and CommonJS too). Both flags can be repeated, and they run in the order you write them.

NODE
// shell: node --require ./setup.cjs --import ./setup.mjs app.js

Try it

Node.js Preloading with --require

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 Order of several preloads

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
// shell
node [-r | --require] <module> [<script>]
node --import <specifier> [<script>]
Name Description
--require <module> / -r Preloads a CommonJS module. The value is resolved like an argument to require(): a relative path starting with ./, an absolute path, or a package name.
--import <specifier> Preloads an ES module (or any module import() can load). Relative paths need ./; file: and data: URLs work too.

Returns: nothing. Preloaded modules run for their side effects. If a preload throws, Node prints the error and exits before the main script starts.

Edge cases: a preload runs once in the main thread. Worker threads and child processes do not inherit the flags unless you pass them (or use NODE_OPTIONS, which child processes inherit through the environment).

Usage notes

  • Order: all --require modules run first, in command-line order, then all --import modules, in command-line order. The relative position of the two flag kinds on the command line does not matter, as the second example shows.
  • Top-level await is awaited. An --import module that awaits something finishes before the next preload or your program begins. A --require module cannot pause startup that way.
  • --import is the right choice for customization hooks. Use it to run register() from node:module before your code is loaded; a data: URL keeps this to one line.
  • Instrumentation tools use these flags. APM agents, loaders for .env files, source-map support and test setup files commonly ship as a module you preload instead of editing every entry file.
  • NODE_OPTIONS: NODE_OPTIONS="--require ./setup.cjs" applies the preload to every Node process started from that environment, including children. See NODE_OPTIONS.
  • Do not mutate globals carelessly. Preloaded code that patches built-ins affects everything that follows, including third-party packages. Keep it small and well named.
  • Common mistake: --require setup.cjs without ./ is treated as a package name and fails with MODULE_NOT_FOUND.
  • --import was added in Node.js 19 and 18.18; --require has existed since the early days.