cli: --dev flag for module resolution and env

Author: guybedford

doc/api/cli.md

@@ -127,6 +127,16 @@ added: v12.0.0
 
 Specify the file name of the CPU profile generated by `--cpu-prof`.
 
+### `--dev`
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Enables the `"development"` [conditional export][] in package resolution,
+while also setting `process.env.NODE_ENV` to `"development"`.
+
 ### `--disable-proto=mode`
 <!--YAML
 added: v13.12.0
@@ -1150,6 +1160,7 @@ node --require "./a.js" --require "./b.js"
 
 Node.js options that are allowed are:
 <!-- node-options-node start -->
+* `--dev`
 * `--disable-proto`
 * `--enable-fips`
 * `--enable-source-maps`
@@ -1495,3 +1506,4 @@ $ node --max-old-space-size=1536 index.js
 [jitless]: https://v8.dev/blog/jitless
 [libuv threadpool documentation]: http://docs.libuv.org/en/latest/threadpool.html
 [remote code execution]: https://www.owasp.org/index.php/Code_Injection
+[conditional export]: esm.html##esm_conditional_exports

doc/api/esm.md

@@ -358,6 +358,8 @@ Node.js supports the following conditions:
 * `"node"` - matched for any Node.js environment. Can be a CommonJS or ES
    module file. _This condition should always come after `"import"` or
    `"require"`._
+* `"development"` - enabled by the `--dev` flag in Node.js, this allows code
+   paths to be loaded that provide additional debugging information.
 * `"default"` - the generic fallback that will always match. Can be a CommonJS
    or ES module file. _This condition should always come last._
 
@@ -383,6 +385,10 @@ Conditional exports can also be extended to exports subpaths, for example:
   "exports": {
     ".": "./main.js",
     "./feature": {
+      "development": {
+        "browser": "./feature-browser-dev.js",
+        "default": "./feature-dev.js"
+      },
       "browser": "./feature-browser.js",
       "default": "./feature.js"
     }
@@ -392,7 +398,8 @@ Conditional exports can also be extended to exports subpaths, for example:
 
 Defines a package where `require('pkg/feature')` and `import 'pkg/feature'`
 could provide different implementations between the browser and Node.js,
-given third-party tool support for a `"browser"` condition.
+given third-party tool support for a `"browser"` condition, as well as
+loading different code between development and production environments.
 
 #### Nested conditions
 
@@ -1471,8 +1478,8 @@ future updates.
 In the following algorithms, all subroutine errors are propagated as errors
 of these top-level routines unless stated otherwise.
 
-_defaultEnv_ is the conditional environment name priority array,
-`["node", "import"]`.
+_defaultEnv_ is the conditional environment array, `["node", "import"]`,
+including the `"development"` condition if the `--dev` flag is set.
 
 The resolver can throw the following errors:
 * _Invalid Module Specifier_: Module specifier is an invalid URL, package name

doc/node.1

@@ -100,6 +100,9 @@ The default is
 File name of the V8 CPU profile generated with
 .Fl -cpu-prof
 .
+.It Fl -dev
+Sets the development exports resolution and NODE_ENV environment variable.
+.
 .It Fl -disable-proto Ns = Ns Ar mode
 Disable the `Object.prototype.__proto__` property. If
 .Ar mode

lib/internal/bootstrap/pre_execution.js

@@ -174,6 +174,9 @@ function initializeReport() {
 }
 
 function setupDebugEnv() {
+  if (getOptionValue('--dev')) {
+    process.env.NODE_ENV = 'development';
+  }
   require('internal/util/debuglog').initializeDebugEnv(process.env.NODE_DEBUG);
   if (getOptionValue('--expose-internals')) {
     require('internal/bootstrap/loaders').NativeModule.exposeInternals();

lib/internal/modules/cjs/loader.js

@@ -71,6 +71,7 @@ const {
   loadNativeModule
 } = require('internal/modules/cjs/helpers');
 const { getOptionValue } = require('internal/options');
+const development = getOptionValue('--dev');
 const enableSourceMaps = getOptionValue('--enable-source-maps');
 const preserveSymlinks = getOptionValue('--preserve-symlinks');
 const preserveSymlinksMain = getOptionValue('--preserve-symlinks-main');
@@ -575,6 +576,16 @@ function resolveExportsTarget(baseUrl, target, subpath, mappingKey) {
     }
     for (const p of keys) {
       switch (p) {
+        case 'development':
+          if (development) {
+            try {
+              return resolveExportsTarget(baseUrl, target[p], subpath,
+                                          mappingKey);
+            } catch (e) {
+              if (e.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') throw e;
+            }
+          }
+          break;
         case 'node':
         case 'require':
           try {

lib/internal/modules/esm/resolve.js

@@ -33,6 +33,7 @@ const { sep } = require('path');
 
 const preserveSymlinks = getOptionValue('--preserve-symlinks');
 const preserveSymlinksMain = getOptionValue('--preserve-symlinks-main');
+const development = getOptionValue('--dev');
 const typeFlag = getOptionValue('--input-type');
 const { URL, pathToFileURL, fileURLToPath } = require('internal/url');
 const {
@@ -46,7 +47,11 @@ const {
   ERR_UNSUPPORTED_ESM_URL_SCHEME,
 } = require('internal/errors').codes;
 
-const DEFAULT_CONDITIONS = ObjectFreeze(['node', 'import']);
+const DEFAULT_CONDITIONS = ObjectFreeze([
+  'node',
+  'import',
+  ...development ? ['development'] : []
+]);
 const DEFAULT_CONDITIONS_SET = new SafeSet(DEFAULT_CONDITIONS);
 
 function getConditionsSet(conditions) {

src/node_options.cc

@@ -271,6 +271,10 @@ DebugOptionsParser::DebugOptionsParser() {
 }
 
 EnvironmentOptionsParser::EnvironmentOptionsParser() {
+  AddOption("--dev",
+            "experimental development mode",
+            &EnvironmentOptions::development,
+            kAllowedInEnvironment);
   AddOption("--enable-source-maps",
             "experimental Source Map V3 support",
             &EnvironmentOptions::enable_source_maps,

src/node_options.h

@@ -100,6 +100,7 @@ class DebugOptions : public Options {
 class EnvironmentOptions : public Options {
  public:
   bool abort_on_uncaught_exception = false;
+  bool development = false;
   bool enable_source_maps = false;
   bool experimental_json_modules = false;
   bool experimental_modules = false;

test/es-module/test-esm-exports-dev.mjs

@@ -0,0 +1,16 @@
+import '../common/index.mjs';
+import { path } from '../common/fixtures.mjs';
+import { strictEqual } from 'assert';
+import { spawnSync } from 'child_process';
+
+{
+  const output = spawnSync(process.execPath, [path('/pkgexports-dev.mjs')]);
+  console.log(output.stderr.toString());
+  strictEqual(output.stdout.toString().trim(), 'production');
+}
+
+{
+  const output = spawnSync(process.execPath,
+                           ['--dev', path('/pkgexports-dev.mjs')]);
+  strictEqual(output.stdout.toString().trim(), 'development');
+}

test/fixtures/es-module-loaders/loader-with-custom-condition.mjs

@@ -1,8 +1,11 @@
 import {ok, deepStrictEqual} from 'assert';
 
+const dev = process.env.NODE_ENV === 'development';
+
 export async function resolve(specifier, context, defaultResolve) {
   ok(Array.isArray(context.conditions), 'loader receives conditions array');
-  deepStrictEqual([...context.conditions].sort(), ['import', 'node']);
+  deepStrictEqual([...context.conditions].sort(),
+      ['import', 'node', ...dev ? ['development'] : []]);
   return defaultResolve(specifier, {
     ...context,
     conditions: ['custom-condition', ...context.conditions],