doc: document null target pattern

PR-URL: nodejs#38724 Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Derek Lewis <[email protected]> Reviewed-By: James M Snell <[email protected]>
foxxyz · Oct 18, 2021 · ce85107 · ce85107
1 parent 6109f6d
commit ce85107
Showing 1 changed file with 23 additions and 0 deletions.
diff --git a/doc/api/packages.md b/doc/api/packages.md
@@ -357,6 +357,9 @@ For these use cases, subpath export patterns can be used instead:
 }
 ```
 
+**`*` maps expose nested subpaths as it is a string replacement syntax
+only.**
+
 The left hand matching pattern must always end in `*`. All instances of `*` on
 the right hand side will then be replaced with this value, including if it
 contains any `/` separators.
@@ -382,6 +385,26 @@ treating the right hand side target pattern as a `**` glob against the list of
 files within the package. Because `node_modules` paths are forbidden in exports
 targets, this expansion is dependent on only the files of the package itself.
 
+To exclude private subfolders from patterns, `null` targets can be used:
+
+```json
+// ./node_modules/es-module-package/package.json
+{
+  "exports": {
+    "./features/*": "./src/features/*.js",
+    "./features/private-internal/*": null
+  }
+}
+```
+
+```js
+import featureInternal from 'es-module-package/features/private-internal/m';
+// Throws: ERR_PACKAGE_PATH_NOT_EXPORTED
+
+import featureX from 'es-module-package/features/x';
+// Loads ./node_modules/es-module-package/src/features/x.js
+```
+
 ### Exports sugar
 <!--YAML
 added: v12.11.0