Commit 9197a66
doc: copyedit packages.md
Some minor adjustments, mostly moving things to present tense and
avoiding the ambiguity of _may_.
Refs: #35370 (comment)
Backport-PR-URL: #35757
PR-URL: #35427
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>1 parent f507ca9 commit 9197a66
1 file changed
Lines changed: 26 additions & 26 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -90,7 +90,7 @@ import 'commonjs-package/src/index.mjs'; | |||
| 90 | 90 | // Loaded as ES module since .mjs is always loaded as ES module. | |
| 91 | 91 | ``` | |
| 92 | 92 | ||
| 93 | - The `.mjs` and `.cjs` extensions may be used to mix types within the same | ||
| 93 | + The `.mjs` and `.cjs` extensions can be used to mix types within the same | ||
| 94 | 94 | package: | |
| 95 | 95 | ||
| 96 | 96 | * Within a `"type": "module"` package, Node.js can be instructed to | |
@@ -106,7 +106,7 @@ package: | |||
| 106 | 106 | ### `--input-type` flag | |
| 107 | 107 | ||
| 108 | 108 | Strings passed in as an argument to `--eval` (or `-e`), or piped to `node` via | |
| 109 | - `STDIN`, will be treated as [ES modules][] when the `--input-type=module` flag | ||
| 109 | + `STDIN`, are treated as [ES modules][] when the `--input-type=module` flag | ||
| 110 | 110 | is set. | |
| 111 | 111 | ||
| 112 | 112 | ```bash | |
@@ -134,7 +134,7 @@ their package. | |||
| 134 | 134 | ||
| 135 | 135 | If both [`"exports"`][] and [`"main"`][] are defined, the [`"exports"`][] field | |
| 136 | 136 | takes precedence over [`"main"`][]. [`"exports"`][] are not specific to ES | |
| 137 | - modules or CommonJS; [`"main"`][] will be overridden by [`"exports"`][] if it | ||
| 137 | + modules or CommonJS; [`"main"`][] is overridden by [`"exports"`][] if it | ||
| 138 | 138 | exists. As such [`"main"`][] cannot be used as a fallback for CommonJS but it | |
| 139 | 139 | can be used as a fallback for legacy versions of Node.js that do not support the | |
| 140 | 140 | [`"exports"`][] field. | |
@@ -188,13 +188,13 @@ Alternatively a project could choose to export entire folders: | |||
| 188 | 188 | ``` | |
| 189 | 189 | ||
| 190 | 190 | As a last resort, package encapsulation can be disabled entirely by creating an | |
| 191 | - export for the root of the package `"./*": "./*"`. This will expose every file | ||
| 191 | + export for the root of the package `"./*": "./*"`. This exposes every file | ||
| 192 | 192 | in the package at the cost of disabling the encapsulation and potential tooling | |
| 193 | 193 | benefits this provides. As the ES Module loader in Node.js enforces the use of | |
| 194 | 194 | [the full specifier path][], exporting the root rather than being explicit | |
| 195 | 195 | about entry is less expressive than either of the prior examples. Not only | |
| 196 | - will encapsulation be lost but module consumers will be unable to | ||
| 197 | - `import feature from 'my-mod/feature'` as they will need to provide the full | ||
| 196 | + is encapsulation lost but module consumers are unable to | ||
| 197 | + `import feature from 'my-mod/feature'` as they need to provide the full | ||
| 198 | 198 | path `import feature from 'my-mod/feature/index.js`. | |
| 199 | 199 | ||
| 200 | 200 | ### Main entry point export | |
@@ -209,9 +209,9 @@ To set the main entry point for a package, it is advisable to define both | |||
| 209 | 209 | } | |
| 210 | 210 | ``` | |
| 211 | 211 | ||
| 212 | - When defining the [`"exports"`][] field, all subpaths of the package will be | ||
| 212 | + When the [`"exports"`][] field is defined, all subpaths of the package are | ||
| 213 | 213 | encapsulated and no longer available to importers. For example, | |
| 214 | - `require('pkg/subpath.js')` would throw an [`ERR_PACKAGE_PATH_NOT_EXPORTED`][] | ||
| 214 | + `require('pkg/subpath.js')` throws an [`ERR_PACKAGE_PATH_NOT_EXPORTED`][] | ||
| 215 | 215 | error. | |
| 216 | 216 | ||
| 217 | 217 | This encapsulation of exports provides more reliable guarantees | |
@@ -343,20 +343,20 @@ For example, a package that wants to provide different ES module exports for | |||
| 343 | 343 | ||
| 344 | 344 | Node.js supports the following conditions out of the box: | |
| 345 | 345 | ||
| 346 | - * `"import"` - matched when the package is loaded via `import` or | ||
| 346 | + * `"import"` - matches when the package is loaded via `import` or | ||
| 347 | 347 | `import()`, or via any top-level import or resolve operation by the | |
| 348 | 348 | ECMAScript module loader. Applies regardless of the module format of the | |
| 349 | 349 | target file. _Always mutually exclusive with `"require"`._ | |
| 350 | - * `"require"` - matched when the package is loaded via `require()`. The | ||
| 350 | + * `"require"` - matches when the package is loaded via `require()`. The | ||
| 351 | 351 | referenced file should be loadable with `require()` although the condition | |
| 352 | - will be matched regardless of the module format of the target file. Expected | ||
| 352 | + matches regardless of the module format of the target file. Expected | ||
| 353 | 353 | formats include CommonJS, JSON, and native addons but not ES modules as | |
| 354 | 354 | `require()` doesn't support them. _Always mutually exclusive with | |
| 355 | 355 | `"import"`._ | |
| 356 | - * `"node"` - matched for any Node.js environment. Can be a CommonJS or ES | ||
| 356 | + * `"node"` - matches for any Node.js environment. Can be a CommonJS or ES | ||
| 357 | 357 | module file. _This condition should always come after `"import"` or | |
| 358 | 358 | `"require"`._ | |
| 359 | - * `"default"` - the generic fallback that will always match. Can be a CommonJS | ||
| 359 | + * `"default"` - the generic fallback that always matches. Can be a CommonJS | ||
| 360 | 360 | or ES module file. _This condition should always come last._ | |
| 361 | 361 | ||
| 362 | 362 | Within the [`"exports"`][] object, key order is significant. During condition | |
@@ -365,9 +365,9 @@ entries. _The general rule is that conditions should be from most specific to | |||
| 365 | 365 | least specific in object order_. | |
| 366 | 366 | ||
| 367 | 367 | Other conditions such as `"browser"`, `"electron"`, `"deno"`, `"react-native"`, | |
| 368 | - etc. are unknown to, and thus ignored by Node.js. Runtimes or tools other than | ||
| 369 | - Node.js may use them at their discretion. Further restrictions, definitions, or | ||
| 370 | - guidance on condition names may occur in the future. | ||
| 368 | + etc., are unknown to Node.js, and thus ignored. Runtimes or tools other than | ||
| 369 | + Node.js can use them at their discretion. Further restrictions, definitions, or | ||
| 370 | + guidance on condition names might occur in the future. | ||
| 371 | 371 | ||
| 372 | 372 | Using the `"import"` and `"require"` conditions can lead to some hazards, | |
| 373 | 373 | which are further explained in [the dual CommonJS/ES module packages section][]. | |
@@ -534,13 +534,13 @@ when using transpilation via tools like [Babel][] or [`esm`][]. | |||
| 534 | 534 | First, the hazard described in the previous section occurs when a package | |
| 535 | 535 | contains both CommonJS and ES module sources and both sources are provided for | |
| 536 | 536 | use in Node.js, either via separate main entry points or exported paths. A | |
| 537 | - package could instead be written where any version of Node.js receives only | ||
| 538 | - CommonJS sources, and any separate ES module sources the package may contain | ||
| 539 | - could be intended only for other environments such as browsers. Such a package | ||
| 537 | + package might instead be written where any version of Node.js receives only | ||
| 538 | + CommonJS sources, and any separate ES module sources the package might contain | ||
| 539 | + are intended only for other environments such as browsers. Such a package | ||
| 540 | 540 | would be usable by any version of Node.js, since `import` can refer to CommonJS | |
| 541 | 541 | files; but it would not provide any of the advantages of using ES module syntax. | |
| 542 | 542 | ||
| 543 | - A package could also switch from CommonJS to ES module syntax in a [breaking | ||
| 543 | + A package might also switch from CommonJS to ES module syntax in a [breaking | ||
| 544 | 544 | change](https://semver.org/) version bump. This has the disadvantage that the | |
| 545 | 545 | newest version of the package would only be usable in ES module-supporting | |
| 546 | 546 | versions of Node.js. | |
@@ -669,7 +669,7 @@ the package’s management of state is carefully isolated (or the package is | |||
| 669 | 669 | stateless). | |
| 670 | 670 | ||
| 671 | 671 | The reason that state is an issue is because both the CommonJS and ES module | |
| 672 | - versions of the package may get used within an application; for example, the | ||
| 672 | + versions of the package might get used within an application; for example, the | ||
| 673 | 673 | user’s application code could `import` the ES module version while a dependency | |
| 674 | 674 | `require`s the CommonJS version. If that were to occur, two copies of the | |
| 675 | 675 | package would be loaded in memory and therefore two separate states would be | |
@@ -751,7 +751,7 @@ conditional exports for consumers could be to add an export, e.g. | |||
| 751 | 751 | ## Node.js `package.json` field definitions | |
| 752 | 752 | ||
| 753 | 753 | This section describes the fields used by the Node.js runtime. Other tools (such | |
| 754 | - as [npm](https://docs.npmjs.com/creating-a-package-json-file)) may use | ||
| 754 | + as [npm](https://docs.npmjs.com/creating-a-package-json-file)) use | ||
| 755 | 755 | additional fields which are ignored by Node.js and not documented here. | |
| 756 | 756 | ||
| 757 | 757 | The following fields in `package.json` files are used in Node.js: | |
@@ -761,7 +761,7 @@ The following fields in `package.json` files are used in Node.js: | |||
| 761 | 761 | * [`"type"`][] - The package type determining whether to load `.js` files as | |
| 762 | 762 | CommonJS or ES modules. | |
| 763 | 763 | * [`"exports"`][] - Package exports and conditional exports. When present, | |
| 764 | - limits which submodules may be loaded from within the package. | ||
| 764 | + limits which submodules can be loaded from within the package. | ||
| 765 | 765 | * [`"main"`][] - The default module when loading the package, if exports is not | |
| 766 | 766 | specified, and in versions of Node.js prior to the introduction of exports. | |
| 767 | 767 | * [`"imports"`][] - Package imports, for use by modules within the package | |
@@ -787,7 +787,7 @@ changes: | |||
| 787 | 787 | ``` | |
| 788 | 788 | ||
| 789 | 789 | The `"name"` field defines your package’s name. Publishing to the | |
| 790 | - _npm_ registry may require a name that satisfies | ||
| 790 | + _npm_ registry requires a name that satisfies | ||
| 791 | 791 | [certain requirements](https://docs.npmjs.com/files/package.json#name). | |
| 792 | 792 | ||
| 793 | 793 | The `"name"` field can be used in addition to the [`"exports"`][] field to | |
@@ -805,10 +805,10 @@ changes: | |||
| 805 | 805 | ||
| 806 | 806 | * Type: {string} | |
| 807 | 807 | ||
| 808 | - The `"type"` field defines the module format that Node.js will use for all | ||
| 808 | + The `"type"` field defines the module format that Node.js uses for all | ||
| 809 | 809 | `.js` files that have that `package.json` file as their nearest parent. | |
| 810 | 810 | ||
| 811 | - Files ending with `.js` will be loaded as ES modules when the nearest parent | ||
| 811 | + Files ending with `.js` are loaded as ES modules when the nearest parent | ||
| 812 | 812 | `package.json` file contains a top-level field `"type"` with a value of | |
| 813 | 813 | `"module"`. | |
| 814 | 814 | ||
0 commit comments