diff options
author | Guy Bedford <guybedford@gmail.com> | 2019-12-05 05:14:48 +0300 |
---|---|---|
committer | Myles Borins <mylesborins@google.com> | 2019-12-13 18:50:40 +0300 |
commit | e61f4ead9329cc2fa27eeb5a1bf828011df6df18 (patch) | |
tree | 27fe8e96d585ef4df64aee1da01dfa5382e2fac3 /doc/api | |
parent | 1b534d571a0efa4ab8a846b4735611d88adc09ec (diff) |
module: conditional exports import condition
PR-URL: https://github.com/nodejs/node/pull/30799
Reviewed-By: Jan Krems <jan.krems@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/esm.md | 49 | ||||
-rw-r--r-- | doc/api/modules.md | 3 |
2 files changed, 30 insertions, 22 deletions
diff --git a/doc/api/esm.md b/doc/api/esm.md index f834f29fbbe..5245cef465e 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -329,8 +329,8 @@ Node.js and the browser can be written: "main": "./index.js", "exports": { "./feature": { - "browser": "./feature-browser.js", - "default": "./feature-default.js" + "import": "./feature-default.js", + "browser": "./feature-browser.js" } } } @@ -341,16 +341,24 @@ will be used as the final fallback. The conditions supported in Node.js are matched in the following order: -1. `"require"` - matched when the package is loaded via `require()`. - _This is currently only supported behind the - `--experimental-conditional-exports` flag._ -2. `"node"` - matched for any Node.js environment. Can be a CommonJS or ES +1. `"node"` - matched for any Node.js environment. Can be a CommonJS or ES module file. _This is currently only supported behind the - `--experimental-conditional-exports` flag._ -3. `"default"` - the generic fallback that will always match if no other + `--experimental-conditional-exports` flag._ +2. `"require"` - matched when the package is loaded via `require()`. + _This is currently only supported behind the + `--experimental-conditional-exports` flag._ +3. `"import"` - matched when the package is loaded via `import` or + `import()`. Can be any module format, this field does not set the type + interpretation. _This is currently only supported behind the + `--experimental-conditional-exports` flag._ +4. `"default"` - the generic fallback that will always match if no other more specific condition is matched first. Can be a CommonJS or ES module file. +> Setting any of the above flagged conditions for a published package is not +> recommended until they are unflagged to avoid breaking changes to packages in +> future. + Using the `"require"` condition it is possible to define a package that will have a different exported value for CommonJS and ES modules, which can be a hazard in that it can result in having two separate instances of the same @@ -394,8 +402,8 @@ from exports subpaths. { "exports": { ".": { - "require": "./main.cjs", - "default": "./main.js" + "import": "./main.js", + "require": "./main.cjs" } } } @@ -407,8 +415,8 @@ can be written: ```js { "exports": { - "require": "./main.cjs", - "default": "./main.js" + "import": "./main.js", + "require": "./main.cjs" } } ``` @@ -422,8 +430,8 @@ thrown: // Throws on resolution! "exports": { "./feature": "./lib/feature.js", - "require": "./main.cjs", - "default": "./main.js" + "import": "./main.js", + "require": "./main.cjs" } } ``` @@ -508,9 +516,8 @@ ES module wrapper is used for `import` and the CommonJS entry point for `require`. > Note: While `--experimental-conditional-exports` is flagged, a package -> using this pattern will throw when loaded via `require()` in modern -> Node.js, unless package consumers use the `--experimental-conditional-exports` -> flag. +> using this pattern will throw when loaded unless package consumers use the +> `--experimental-conditional-exports` flag. <!-- eslint-skip --> ```js @@ -520,7 +527,7 @@ ES module wrapper is used for `import` and the CommonJS entry point for "main": "./index.cjs", "exports": { "require": "./index.cjs", - "default": "./wrapper.mjs" + "import": "./wrapper.mjs" } } ``` @@ -605,8 +612,8 @@ CommonJS and ES module entry points directly (requires "type": "module", "main": "./index.cjs", "exports": { - "require": "./index.cjs", - "default": "./index.mjs" + "import": "./index.mjs", + "require": "./index.cjs" } } ``` @@ -1149,7 +1156,7 @@ of these top-level routines unless stated otherwise. _isMain_ is **true** when resolving the Node.js application entry point. _defaultEnv_ is the conditional environment name priority array, -`["node", "default"]`. +`["node", "import"]`. <details> <summary>Resolver algorithm specification</summary> diff --git a/doc/api/modules.md b/doc/api/modules.md index 42f42c07fd7..5653fe8f424 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -241,7 +241,8 @@ RESOLVE_BARE_SPECIFIER(DIR, X) g. If no such key can be found, throw "not found". h. let RESOLVED_URL = PACKAGE_EXPORTS_TARGET_RESOLVE(pathToFileURL(DIR/name), exports[key], - subpath.slice(key.length)), as defined in the ESM resolver. + subpath.slice(key.length), ["node", "require"]), as defined in the ESM + resolver. i. return fileURLToPath(RESOLVED_URL) 3. return DIR/X ``` |