From 2909dfdcf1876bf2650f136e9fa28bdd207ea410 Mon Sep 17 00:00:00 2001 From: Phantom-d-e-v <82759425+Phantom-d-e-v@users.noreply.github.com> Date: Fri, 10 Jul 2026 20:54:35 +0000 Subject: [PATCH] doc: document subpath-pattern precedence and null blocking in exports The exports resolution sorts subpath patterns by specificity (lib/internal/modules/esm/resolve.js patternKeyCompare), so the pattern with the longest matching prefix wins regardless of declaration order. A null target blocks any subpath matching its pattern, regardless of key position. The documentation did not state either rule, so add a short clarification after the existing null example. Fixes: https://github.com/nodejs/node/issues/44517 --- doc/api/packages.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/api/packages.md b/doc/api/packages.md index c4781eca106200..5e021746fc5b17 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -655,6 +655,15 @@ import featureX from 'es-module-package/features/x.js'; // Loads ./node_modules/es-module-package/src/features/x.js ``` +When a subpath matches more than one pattern, the pattern with the longest +matching prefix (the most specific pattern) takes precedence, regardless of the +order in which the patterns are declared in the `exports` object. + +A `null` target blocks access to the subpaths that would otherwise match its +pattern: requesting such a subpath throws +[`ERR_PACKAGE_PATH_NOT_EXPORTED`][] regardless of where the `null` pattern is +positioned among the keys. + ### Conditional exports