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.
// shell: node --require ./setup.cjs --import ./setup.mjs app.js
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
// 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
--requiremodules run first, in command-line order, then all--importmodules, 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
awaitis awaited. An--importmodule that awaits something finishes before the next preload or your program begins. A--requiremodule cannot pause startup that way. --importis the right choice for customization hooks. Use it to runregister()fromnode:modulebefore your code is loaded; adata:URL keeps this to one line.- Instrumentation tools use these flags. APM agents, loaders for
.envfiles, 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.cjswithout./is treated as a package name and fails withMODULE_NOT_FOUND. --importwas added in Node.js 19 and 18.18;--requirehas existed since the early days.
Related
require(),module.register(), NODE_OPTIONS,node file- Lessons: Running code, ES modules