FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: move package.import content higher · nodejs/node@1cd1d01 · GitHub

/ node Public

Commit 1cd1d01

Browse files
MylesBorins
committed
doc: move package.import content higher
This is currently at the end of the doc, it likely should be found right after the documentation about `package.exports`. Refactored the docs while duplicating content as little as possible. Co-authored-by: Guy Bedford <guybedford@gmail.com> Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com> Co-authored-by: Rich Trott <rtrott@gmail.com> Signed-off-by: Myles Borins <mylesborins@github.com> PR-URL: #35535 Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
1 parent 79f3c32 commit 1cd1d01

1 file changed

Lines changed: 55 additions & 22 deletions

File tree

‎doc/api/packages.md‎

Lines changed: 55 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -279,13 +279,53 @@ import submodule from 'es-module-package/private-module.js';
279279
// Throws ERR_PACKAGE_PATH_NOT_EXPORTED
280280
```
281281

282-
### Subpath export patterns
282+
### Subpath imports
283283

284284
> Stability: 1 - Experimental
285285
286-
For packages with a small number of exports, we recommend explicitly listing
287-
each exports subpath entry. But for packages that have large numbers of
288-
subpaths, this might cause `package.json` bloat and maintenance issues.
286+
In addition to the [`"exports"`][] field, it is possible to define internal
287+
package import maps that only apply to import specifiers from within the package
288+
itself.
289+
290+
Entries in the imports field must always start with `#` to ensure they are
291+
disambiguated from package specifiers.
292+
293+
For example, the imports field can be used to gain the benefits of conditional
294+
exports for internal modules:
295+
296+
```json
297+
// package.json
298+
{
299+
"imports": {
300+
"#dep": {
301+
"node": "dep-node-native",
302+
"default": "./dep-polyfill.js"
303+
}
304+
},
305+
"dependencies": {
306+
"dep-node-native": "^1.0.0"
307+
}
308+
}
309+
```
310+
311+
where `import '#dep'` does not get the resolution of the external package
312+
`dep-node-native` (including its exports in turn), and instead gets the local
313+
file `./dep-polyfill.js` relative to the package in other environments.
314+
315+
Unlike the `"exports"` field, the `"imports"` field permits mapping to external
316+
packages.
317+
318+
The resolution rules for the imports field are otherwise
319+
analogous to the exports field.
320+
321+
### Subpath patterns
322+
323+
> Stability: 1 - Experimental
324+
325+
For packages with a small number of exports or imports, we recommend
326+
explicitly listing each exports subpath entry. But for packages that have
327+
large numbers of subpaths, this might cause `package.json` bloat and
328+
maintenance issues.
289329

290330
For these use cases, subpath export patterns can be used instead:
291331

@@ -294,6 +334,9 @@ For these use cases, subpath export patterns can be used instead:
294334
{
295335
"exports": {
296336
"./features/*": "./src/features/*.js"
337+
},
338+
"imports": {
339+
"#internal/*": "./src/internal/*.js"
297340
}
298341
}
299342
```
@@ -308,6 +351,9 @@ import featureX from 'es-module-package/features/x';
308351

309352
import featureY from 'es-module-package/features/y/y';
310353
// Loads ./node_modules/es-module-package/src/features/y/y.js
354+
355+
import internalZ from '#internal/z';
356+
// Loads ./node_modules/es-module-package/src/internal/z.js
311357
```
312358

313359
This is a direct static replacement without any special handling for file
@@ -947,16 +993,6 @@ added: v12.19.0
947993

948994
* Type: {Object}
949995

950-
In addition to the [`"exports"`][] field it is possible to define internal
951-
package import maps that only apply to import specifiers from within the package
952-
itself.
953-
954-
Entries in the imports field must always start with `#` to ensure they are
955-
clearly disambiguated from package specifiers.
956-
957-
For example, the imports field can be used to gain the benefits of conditional
958-
exports for internal modules:
959-
960996
```json
961997
// package.json
962998
{
@@ -972,15 +1008,11 @@ exports for internal modules:
9721008
}
9731009
```
9741010

975-
where `import '#dep'` would now get the resolution of the external package
976-
`dep-node-native` (including its exports in turn), and instead get the local
977-
file `./dep-polyfill.js` relative to the package in other environments.
1011+
Entries in the imports field must be strings starting with `#`.
9781012

979-
Unlike the `"exports"` field, import maps permit mapping to external packages,
980-
providing an important use case for conditional loading scenarios.
1013+
Import maps permit mapping to external packages.
9811014

982-
Apart from the above, the resolution rules for the imports field are otherwise
983-
analogous to the exports field.
1015+
This field defines [subpath imports][] for the current package.
9841016

9851017
[Babel]: https://babeljs.io/
9861018
[Conditional exports]: #packages_conditional_exports
@@ -998,5 +1030,6 @@ analogous to the exports field.
9981030
[`package.json`]: #packages_node_js_package_json_field_definitions
9991031
[self-reference]: #packages_self_referencing_a_package_using_its_name
10001032
[subpath exports]: #packages_subpath_exports
1001-
[the full specifier path]: modules_esm.html#modules_esm_mandatory_file_extensions
1033+
[subpath imports]: #packages_subpath_imports
1034+
[the full specifier path]: esm.md#esm_mandatory_file_extensions
10021035
[the dual CommonJS/ES module packages section]: #packages_dual_commonjs_es_module_packages

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL