Skip to content

doc: packages docs feedback #35370

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
guybedford wants to merge 9 commits into from
Closed

doc: packages docs feedback #35370

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d054ee0
doc: packages docs feedback
guybedford Sep 27, 2020
4f9495c
fixups
guybedford Sep 27, 2020
0598dc9
pr feedbackg
guybedford Sep 27, 2020
7df9cd7
keep nearest parent phrases
guybedford Sep 28, 2020
896b1ff
package boundary suggestions
guybedford Sep 28, 2020
2a19db1
Apply suggestions from code review
guybedford Sep 28, 2020
3a35054
further feedback
guybedford Sep 28, 2020
272a18c
remove unused definition
guybedford Sep 28, 2020
1ebef9a
Update doc/api/packages.md
guybedford Sep 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
further feedback
  • Loading branch information
@guybedford
guybedford committed Sep 28, 2020
commit 3a35054e9a22faf1b33e514b983cfdfb9c327270
14 changes: 3 additions & 11 deletions doc/api/packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,12 +49,6 @@ files in the package should be interpreted.

### `package.json` and file extensions

A folder containing a `package.json` file, and all subfolders below that folder
until the next folder containing another [`package.json`][], are a
_package boundary_. Package boundaries do not carry through `node_modules`
folders, which are effectively treated as if they contained an empty
`package.json`.

Within a package, the [`package.json`][] [`"type"`][] field defines how
Node.js should interpret `.js` files. If a `package.json` file does not have a
`"type"` field, `.js` files are treated as [CommonJS][].
Expand Down Expand Up @@ -87,7 +81,6 @@ the nearest parent `package.json`.

Files ending with `.cjs` are always loaded as [CommonJS][] regardless of the
nearest parent `package.json`.
boundary.

```js
import './legacy-file.cjs';
Expand Down Expand Up @@ -761,8 +754,7 @@ This section describes the fields used by the Node.js runtime. Other tools (such
as [npm](https://docs.npmjs.com/creating-a-package-json-file)) may use
additional fields which are ignored by Node.js and not documented here.

The following fields in `package.json` files are relevant to the Node.js module
loading system, and are described in detail below.
The following fields in `package.json` files are used in Node.js:

* [`"name"`][] - Relevant when using named imports within a package. Also used
by package managers as the name of the package.
Expand Down Expand Up @@ -817,7 +809,7 @@ changes:
* Type: {string}

The `"type"` field defines the module format that Node.js will use for all
`.js` files that have that `package.json` file as their [package boundary][].
`.js` files that have that `package.json` file as their nearest parent.

Files ending with `.js` will be loaded as ES modules when the nearest parent
`package.json` file contains a top-level field `"type"` with a value of
Expand Down Expand Up @@ -979,7 +971,7 @@ analogous to the exports field.
[`"type"`]: #packages_type
[entry points]: #packages_package_entry_points
[`package.json`]: #packages_node_js_package_json_field_definitions
[package boundary]: #packages_package_boundaries_and_file_extensions
[`package.json` and file extensions]: #packages_package_json_and_file_extensions
[self-reference]: #packages_self_referencing_a_package_using_its_name
[subpath exports]: #packages_subpath_exports
[the full specifier path]: modules_esm.html#modules_esm_mandatory_file_extensions
Expand Down