Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js --conditions flag

Reference for node --conditions (-C): enable extra package.json export and import conditions such as development, and see how they pick a file.

--conditions=<name> (short form -C <name>) adds a custom condition to the list Node.js uses when it resolves a package through the exports or imports fields of package.json. Packages can then offer different files depending on which condition is active, for example a verbose development build and a lean default build.

Node always matches the built-in conditions (node, import or require, and default). Conditions you add with the flag are matched too, in the order the package author listed them.

NODE
// shell: node --conditions=development app.js

Try it

Node.js A package with a development build

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 inside exports matters

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 --conditions=<name> <script>
node -C <name> <script>
Name Description
<name> A condition name such as development, production or a tool-specific word. The flag may be repeated to add several.

Returns: nothing. It changes which file import and require() pick for packages that use conditional exports or imports.

Edge cases: the flag has no effect on a package that has no condition with that name, and it never overrides the order of keys: Node walks the object from top to bottom and takes the first key that matches an active condition.

Usage notes

  • Order is the rule. Put specific conditions (development, types, your custom name) before default. A default key listed first swallows everything below it, as the second example shows.
  • Built-in conditions: node, node-addons, import, require, module-sync, and default are matched without any flag. Names such as development and production are only a convention; Node does not set them on its own.
  • Monorepos and source-first development: teams often add a custom condition (say source) in each workspace package that points at src/index.ts, then run tools with --conditions=source to skip the build step.
  • Applies to the whole process, including packages deep in node_modules. If a dependency happens to use the same condition name, it switches too.
  • Child processes inherit the setting only through NODE_OPTIONS or if you pass the flag again.
  • NODE_OPTIONS accepts --conditions / -C, so NODE_OPTIONS="-C development" works for tools that launch Node for you.
  • process.execArgv lists the flags given to Node itself exactly as typed (['-C', 'browserish'] in the second example), separate from process.argv.