doc: document null target pattern

guybedford · danielleadams · commit 96fa38708224 · 2021-05-31T15:34:48.000-04:00
PR-URL: #38724 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is> Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/api/packages.md b/doc/api/packages.md
@@ -358,6 +358,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.
@@ -383,6 +386,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
+```
+
 ### Subpath folder mappings
 <!-- YAML
 changes:
