doc: recommend package exports instead of requiring folders

aduh95 · BethGriggs · commit 6370b4df68da · 2022-01-24T17:35:42.000Z
PR-URL: #41381 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
diff --git a/doc/api/modules.md b/doc/api/modules.md
@@ -436,8 +436,8 @@ If the given path does not exist, `require()` will throw an [`Error`][] with its
 
 <!--type=misc-->
 
-It is convenient to organize programs and libraries into self-contained
-directories, and then provide a single entry point to those directories.
+> Stability: 3 - Legacy: Use [subpath exports][] or [subpath imports][] instead.
+
 There are three ways in which a folder may be passed to `require()` as
 an argument.
 
@@ -454,8 +454,6 @@ If this was in a folder at `./some-library`, then
 `require('./some-library')` would attempt to load
 `./some-library/lib/some-library.js`.
 
-This is the extent of the awareness of `package.json` files within Node.js.
-
 If there is no [`package.json`][] file present in the directory, or if the
 [`"main"`][] entry is missing or cannot be resolved, then Node.js
 will attempt to load an `index.js` or `index.node` file out of that
@@ -472,6 +470,11 @@ with the default error:
 Error: Cannot find module 'some-library'
 ```
 
+In all three above cases, an `import('./some-library')` call would result in a
+[`ERR_UNSUPPORTED_DIR_IMPORT`][] error. Using package [subpath exports][] or
+[subpath imports][] can provide the same containment organization benefits as
+folders as modules, and work for both `require` and `import`.
+
 ## Loading from `node_modules` folders
 
 <!--type=misc-->
@@ -1080,6 +1083,7 @@ This section was moved to
 [`"main"`]: packages.md#main
 [`"type"`]: packages.md#type
 [`ERR_REQUIRE_ESM`]: errors.md#err_require_esm
+[`ERR_UNSUPPORTED_DIR_IMPORT`]: errors.md#err_unsupported_dir_import
 [`Error`]: errors.md#class-error
 [`__dirname`]: #__dirname
 [`__filename`]: #__filename
@@ -1094,3 +1098,5 @@ This section was moved to
 [exports shortcut]: #exports-shortcut
 [module resolution]: #all-together
 [native addons]: addons.md
+[subpath exports]: packages.md#subpath-exports
+[subpath imports]: packages.md#subpath-imports
