doc: clarify conditional exports guidance

PR-URL: #34306 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Jan Krems <[email protected]>
nodejs · Sep 22, 2020 · 7be8dde · 7be8dde
1 parent c1b5c89
commit 7be8dde
Showing 1 changed file with 13 additions and 5 deletions.
diff --git a/doc/api/esm.md b/doc/api/esm.md
@@ -456,16 +456,24 @@ Conditional exports can also be extended to exports subpaths, for example:
   "exports": {
     ".": "./main.js",
     "./feature": {
-      "browser": "./feature-browser.js",
+      "node": "./feature-node.js",
       "default": "./feature.js"
     }
   }
 }
 ```
 
 Defines a package where `require('pkg/feature')` and `import 'pkg/feature'`
-could provide different implementations between the browser and Node.js,
-given third-party tool support for a `"browser"` condition.
+could provide different implementations between Node.js and other JS
+environments.
+
+When using environment branches, always include a `"default"` condition where
+possible. Providing a `"default"` condition ensures that any unknown JS
+environments are able to use this universal implementation, which helps avoid
+these JS environments from having to pretend to be existing environments in
+order to support packages with conditional exports. For this reason, using
+`"node"` and `"default"` condition branches is usually preferable to using
+`"node"` and `"browser"` condition branches.
 
 #### Nested conditions
 
@@ -479,11 +487,11 @@ use in Node.js but not the browser:
 {
   "main": "./main.js",
   "exports": {
-    "browser": "./feature-browser.mjs",
     "node": {
       "import": "./feature-node.mjs",
       "require": "./feature-node.cjs"
-    }
+    },
+    "default": "./feature.mjs",
   }
 }
 ```