Skip to content

Commit

Permalink
doc: recommend package exports instead of requiring folders
Browse files Browse the repository at this point in the history
PR-URL: #41381
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
  • Loading branch information
aduh95 authored and BethGriggs committed Jan 24, 2022
1 parent b5104e8 commit 6370b4d
Showing 1 changed file with 10 additions and 4 deletions.
14 changes: 10 additions & 4 deletions doc/api/modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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-->
Expand Down Expand Up @@ -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
Expand All @@ -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

0 comments on commit 6370b4d

Please sign in to comment.