8000
We read every piece of feedback, and take your input very seriously.
To see all available qualifiers, see our documentation.
There was an error while loading. Please reload this page.
1 parent 368a3ae commit 4dbb3a9Copy full SHA for 4dbb3a9
doc/api/packages.md
@@ -90,7 +90,7 @@ import 'commonjs-package/src/index.mjs';
90
// Loaded as ES module since .mjs is always loaded as ES module.
91
```
92
93
-The `.mjs` and `.cjs` extensions may be used to mix types within the same
+The `.mjs` and `.cjs` extensions can be used to mix types within the same
94
package:
95
96
* Within a `"type": "module"` package, Node.js can be instructed to
@@ -106,7 +106,7 @@ package:
106
### `--input-type` flag
107
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
+`STDIN`, are treated as [ES modules][] when the `--input-type=module` flag
110
is set.
111
112
```bash
@@ -134,7 +134,7 @@ their package.
134
135
If both [`"exports"`][] and [`"main"`][] are defined, the [`"exports"`][] field
136
takes precedence over [`"main"`][]. [`"exports"`][] are not specific to ES
137
-modules or CommonJS; [`"main"`][] will be overridden by [`"exports"`][] if it
+modules or CommonJS; [`"main"`][] is overridden by [`"exports"`][] if it
138
exists. As such [`"main"`][] cannot be used as a fallback for CommonJS but it
139
can be used as a fallback for legacy versions of Node.js that do not support the
140
[`"exports"`][] field.
@@ -188,13 +188,13 @@ Alternatively a project could choose to export entire folders:
188
189
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
+export for the root of the package `"./*": "./*"`. This exposes every file
192
in the package at the cost of disabling the encapsulation and potential tooling
193
benefits this provides. As the ES Module loader in Node.js enforces the use of
194
[the full specifier path][], exporting the root rather than being explicit
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
+is encapsulation lost but module consumers are unable to
+`import feature from 'my-mod/feature'` as they need to provide the full
198
path `import feature from 'my-mod/feature/index.js`.
199
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
}
210
211
212
-When defining the [`"exports"`][] field, all subpaths of the package will be
+When the [`"exports"`][] field is defined, all subpaths of the package are
213
encapsulated and no longer available to importers. For example,
214
-`require('pkg/subpath.js')` would throw an [`ERR_PACKAGE_PATH_NOT_EXPORTED`][]
+`require('pkg/subpath.js')` throws an [`ERR_PACKAGE_PATH_NOT_EXPORTED`][]
215
error.
216
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
344
Node.js supports the following conditions out of the box:
345
346
-* `"import"` - matched when the package is loaded via `import` or
+* `"import"` - matches when the package is loaded via `import` or
347
`import()`, or via any top-level import or resolve operation by the
348
ECMAScript module loader. Applies regardless of the module format of the
349
target file. _Always mutually exclusive with `"require"`._
350
-* `"require"` - matched when the package is loaded via `require()`. The
+* `"require"` - matches when the package is loaded via `require()`. The
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
+ matches regardless of the module format of the target file. Expected
353
formats include CommonJS, JSON, and native addons but not ES modules as
354
`require()` doesn't support them. _Always mutually exclusive with
355
`"import"`._
356
-* `"node"` - matched for any Node.js environment. Can be a CommonJS or ES
+* `"node"` - matches for any Node.js environment. Can be a CommonJS or ES
357
module file. _This condition should always come after `"import"` or
358
`"require"`._
359
-* `"default"` - the generic fallback that will always match. Can be a CommonJS
+* `"default"` - the generic fallback that always matches. Can be a CommonJS
360
or ES module file. _This condition should always come last._
361
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
least specific in object order_.
366
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.
+etc., are unknown to Node.js, and thus ignored. Runtimes or tools other than
+Node.js can use them at their discretion. Further restrictions, definitions, or
+guidance on condition names might occur in the future.
371
372
Using the `"import"` and `"require"` conditions can lead to some hazards,
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
First, the hazard described in the previous section occurs when a package
535
contains both CommonJS and ES module sources and both sources are provided for
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
+package might instead be written where any version of Node.js receives only
+CommonJS sources, and any separate ES module sources the package might contain
+are intended only for other environments such as browsers. Such a package
540
would be usable by any version of Node.js, since `import` can refer to CommonJS
541
files; but it would not provide any of the advantages of using ES module syntax.
542
543
-A package could also switch from CommonJS to ES module syntax in a [breaking
+A package 23CB might also switch from CommonJS to ES module syntax in a [breaking
544
change](https://semver.org/) version bump. This has the disadvantage that the
545
newest version of the package would only be usable in ES module-supporting
546
versions of Node.js.
@@ -669,7 +669,7 @@ the package’s management of state is carefully isolated (or the package is
669
stateless).
670
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
+versions of the package might get used within an application; for example, the
673
user’s application code could `import` the ES module version while a dependency
674
`require`s the CommonJS version. If that were to occur, two copies of the
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
## Node.js `package.json` field definitions
752
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
+as [npm](https://docs.npmjs.com/creating-a-package-json-file)) use
755
additional fields which are ignored by Node.js and not documented here.
756
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
* [`"type"`][] - The package type determining whether to load `.js` files as
762
CommonJS or ES modules.
763
* [`"exports"`][] - Package exports and conditional exports. When present,
764
- limits which submodules may be loaded from within the package.
+ limits which submodules can be loaded from within the package.
765
* [`"main"`][] - The default module when loading the package, if exports is not
766
specified, and in versions of Node.js prior to the introduction of exports.
767
* [`"imports"`][] - Package imports, for use by modules within the package
@@ -789,7 +789,7 @@ changes:
789
790
791
The `"name"` field defines your package’s name. Publishing to the
792
-_npm_ registry may require a name that satisfies
+_npm_ registry requires a name that satisfies
793
[certain requirements](https://docs.npmjs.com/files/package.json#name).
794
795
The `"name"` field can be used in addition to the [`"exports"`][] field to
@@ -808,10 +808,10 @@ changes:
808
809
* Type: {string}
810
811
-The `"type"` field defines the module format that Node.js will use for all
+The `"type"` field defines the module format that Node.js uses for all
812 23CB code>
812
`.js` files that have that `package.json` file as their nearest parent.
813
814
-Files ending with `.js` will be loaded as ES modules when the nearest parent
+Files ending with `.js` are loaded as ES modules when the nearest parent
815
`package.json` file contains a top-level field `"type"` with a value of
816
`"module"`.
817