Lines Matching +full:node +full:- +full:version
3 <!--introduced_in=v12.20.0-->
4 <!-- type=misc -->
5 <!-- YAML
7 - version:
8 - v14.13.0
9 pr-url: https://github.com/nodejs/node/pull/34718
11 - version:
12 - v14.6.0
13 - v12.19.0
14 pr-url: https://github.com/nodejs/node/pull/34117
16 - version:
17 - v13.7.0
18 - v12.16.0
19 pr-url: https://github.com/nodejs/node/pull/31001
21 - version:
22 - v13.6.0
23 - v12.16.0
24 pr-url: https://github.com/nodejs/node/pull/31002
25 description: Unflag self-referencing a package using its name.
26 - version: v12.7.0
27 pr-url: https://github.com/nodejs/node/pull/28568
31 - version: v12.0.0
32 pr-url: https://github.com/nodejs/node/pull/26745
36 -->
46 along with a reference for the [`package.json`][] fields defined by Node.js.
50 Node.js will treat the following as [ES modules][] when passed to `node` as the
56 top-level [`"type"`][] field with a value of `"module"`.
58 * Strings passed in as an argument to `--eval`, or piped to `node` via `STDIN`,
59 with the flag `--input-type=module`.
61 Node.js will treat as [CommonJS][] all other forms of input, such as `.js` files
62 where the nearest parent `package.json` file contains no top-level `"type"`
63 field, or string input without the flag `--input-type`. This behavior is to
64 preserve backward compatibility. However, now that Node.js supports both
65 CommonJS and ES modules, it is best to be explicit whenever possible. Node.js
66 will treat the following as CommonJS when passed to `node` as the initial input,
72 top-level field [`"type"`][] with a value of `"commonjs"`.
74 * Strings passed in as an argument to `--eval` or `--print`, or piped to `node`
75 via `STDIN`, with the flag `--input-type=commonjs`.
79 future-proof the package in case the default type of Node.js ever changes, and
86 Node.js should interpret `.js` files. If a `package.json` file does not have a
89 A `package.json` `"type"` value of `"module"` tells Node.js to interpret `.js`
92 The `"type"` field applies not only to initial entry points (`node my-app.js`)
96 // my-app.js, treated as an ES module because there is a package.json
103 import 'commonjs-package';
104 // Loaded as CommonJS since ./node_modules/commonjs-package/package.json
107 import './node_modules/commonjs-package/index.js';
108 // Loaded as CommonJS since ./node_modules/commonjs-package/package.json
119 import './legacy-file.cjs';
122 import 'commonjs-package/src/index.mjs';
129 * Within a `"type": "module"` package, Node.js can be instructed to
134 * Within a `"type": "commonjs"` package, Node.js can be instructed to
139 ### `--input-type` flag
140 <!-- YAML
142 -->
144 Strings passed in as an argument to `--eval` (or `-e`), or piped to `node` via
145 `STDIN`, are treated as [ES modules][] when the `--input-type=module` flag
149 node --input-type=module --eval "import { sep } from 'path'; console.log(sep);"
151 echo "import { sep } from 'path'; console.log(sep);" | node --input-type=module
154 For completeness there is also `--input-type=commonjs`, for explicitly running
155 string input as CommonJS. This is the default behavior if `--input-type` is
160 > Stability: 1 - Experimental
162 While all Node.js projects are expected to be installable by all package
164 specific package manager. To make this process easier, Node.js ships with a
166 available in your environment - provided you have Node.js installed.
169 the generic "Last Known Good" versions associated with each Node.js release,
177 in all versions of Node.js, but its capabilities are limited: it only defines
190 can be used as a fallback for legacy versions of Node.js that do not support the
201 [`package.json`][] (e.g. `require('your-package/package.json')`. **This will
204 To make the introduction of [`"exports"`][] non-breaking, ensure that every
206 entry points so that the package’s public API is well-defined. For example,
212 "name": "my-mod",
229 "name": "my-mod",
244 benefits this provides. As the ES Module loader in Node.js enforces the use of
248 `import feature from 'my-mod/feature'` as they need to provide the full
249 path `import feature from 'my-mod/feature/index.js`.
275 <!-- YAML
277 -->
296 import submodule from 'es-module-package/submodule';
297 // Loads ./node_modules/es-module-package/src/submodule.js
303 import submodule from 'es-module-package/private-module.js';
308 <!-- YAML
310 - v14.6.0
311 - v12.19.0
312 -->
329 "node": "dep-node-native",
330 "default": "./dep-polyfill.js"
334 "dep-node-native": "^1.0.0"
340 `dep-node-native` (including its exports in turn), and instead gets the local
341 file `./dep-polyfill.js` relative to the package in other environments.
350 <!-- YAML
352 - v14.13.0
353 - v12.20.0
354 -->
364 // ./node_modules/es-module-package/package.json
382 import featureX from 'es-module-package/features/x';
383 // Loads ./node_modules/es-module-package/src/features/x.js
385 import featureY from 'es-module-package/features/y/y';
386 // Loads ./node_modules/es-module-package/src/features/y/y.js
389 // Loads ./node_modules/es-module-package/src/internal/z.js
405 // ./node_modules/es-module-package/package.json
409 "./features/private-internal/*": null
415 import featureInternal from 'es-module-package/features/private-internal/m';
418 import featureX from 'es-module-package/features/x';
419 // Loads ./node_modules/es-module-package/src/features/x.js
423 <!-- YAML
425 -->
450 <!-- YAML
452 - v13.2.0
453 - v12.16.0
455 - version:
456 - v13.7.0
457 - v12.16.0
458 pr-url: https://github.com/nodejs/node/pull/31001
460 -->
471 "main": "./main-require.cjs",
473 "import": "./main-module.js",
474 "require": "./main-require.cjs"
480 Node.js implements the following conditions:
482 * `"import"` - matches when the package is loaded via `import` or
483 `import()`, or via any top-level import or resolve operation by the
486 * `"require"` - matches when the package is loaded via `require()`. The
492 * `"node"` - matches for any Node.js environment. Can be a CommonJS or ES
495 * `"node-addons"` - similar to `"node"` and matches for any Node.js environment.
499 [`--no-addons` flag][].
500 * `"default"` - the generic fallback that always matches. Can be a CommonJS
519 "node": "./feature-node.js",
527 could provide different implementations between Node.js and other JS
535 `"node"` and `"default"` condition branches is usually preferable to using
536 `"node"` and `"browser"` condition branches.
540 In addition to direct mappings, Node.js also supports nested condition objects.
543 use in Node.js but not the browser:
549 "node": {
550 "import": "./feature-node.mjs",
551 "require": "./feature-node.cjs"
564 <!-- YAML
566 - v14.9.0
567 - v12.19.0
568 -->
570 When running Node.js, custom user conditions can be added with the
571 `--conditions` flag:
574 node --conditions=development main.js
578 exports, while resolving the existing `"node"`, `"node-addons"`, `"default"`,
585 The `"import"`, `"require"`, `"node"`, `"node-addons"` and `"default"`
586 conditions are defined and implemented in Node.js core,
589 The `"node-addons"` condition can be used to provide an entry point which
591 [`--no-addons` flag][]. When using `"node-addons"`, it's recommended to treat
595 Other condition strings are unknown to Node.js and thus ignored by default.
596 Runtimes or tools other than Node.js can use them at their discretion.
598 These user conditions can be enabled in Node.js via the [`--conditions`
601 The following condition definitions are currently endorsed by Node.js:
603 * `"browser"` - any environment which implements a standard subset of global
606 * `"development"` - can be used to define a development-only environment
608 * `"production"` - can be used to define a production environment entry
611 The above user conditions can be enabled in Node.js via the [`--conditions`
614 Platform specific conditions such as `"deno"`, `"electron"`, or `"react-native"`
616 from these platforms, the above are not explicitly endorsed by Node.js.
619 to the [Node.js documentation for this section][]. The requirements for listing
629 this would not necessarily be the case for company-specific or
630 application-specific conditions.
635 ### Self-referencing a package using its name
636 <!-- YAML
638 - v13.1.0
639 - v12.16.0
641 - version:
642 - v13.6.0
643 - v12.16.0
644 pr-url: https://github.com/nodejs/node/pull/31002
645 description: Unflag self-referencing a package using its name.
646 -->
655 "name": "a-package",
666 // ./a-module.mjs
667 import { something } from 'a-package'; // Imports "something" from ./main.mjs.
670 Self-referencing is available only if `package.json` has [`"exports"`][], and
676 // ./another-module.mjs
681 import { another } from 'a-package/m.mjs';
684 Self-referencing is also available when using `require`, both in an ES module,
688 // ./a-module.js
689 const { something } = require('a-package/foo'); // Loads from ./foo.js.
692 Finally, self-referencing also works with scoped packages. For example, this
714 $ node other.js
720 Prior to the introduction of support for ES modules in Node.js, it was a common
725 This enabled Node.js to run the CommonJS entry point while build tools such as
726 bundlers used the ES module entry point, since Node.js ignored (and still
727 ignores) the top-level `"module"` field.
729 Node.js can now run ES module entry points, and a package can contain both
731 `'pkg'` and `'pkg/es-module'`, or both at the same specifier via [Conditional
734 Node.js, the files referenced by the ES module entry point are evaluated as ES
747 directly, it is common for an application to load one version while a dependency
748 of the application loads the other version. This hazard can happen because
749 Node.js supports intermixing CommonJS and ES modules, and can lead to unexpected
756 all-CommonJS or all-ES module environments, respectively, and therefore is
764 use in Node.js, either via separate main entry points or exported paths. A
765 package might instead be written where any version of Node.js receives only
768 would be usable by any version of Node.js, since `import` can refer to CommonJS
772 change](https://semver.org/) version bump. This has the disadvantage that the
773 newest version of the package would only be usable in ES module-supporting
774 versions of Node.js.
780 1. The package is usable in both current Node.js and older versions of Node.js
850 package is used directly in an application, and a `utilities-plus` package
852 underlying CommonJS files, it doesn’t matter if `utilities-plus` is written in
858 be to add an export, e.g. `"./module"`, to point to an all-ES module-syntax
859 version of the package. This could be used via `import 'pkg/module'` by users
860 who are certain that the CommonJS version will not be loaded anywhere in the
861 application, such as by dependencies; or if the CommonJS version can be loaded
862 but doesn’t affect the ES module version (for example, because the package is
901 user’s application code could `import` the ES module version while a dependency
902 `require`s the CommonJS version. If that were to occur, two copies of the
904 present. This would likely cause hard-to-troubleshoot bugs.
922 object, or modify a passed-in object, to keep the state external to the
953 wants that version to be used wherever such syntax is supported.
965 `"./module"`, to point to an all-ES module-syntax version of the package:
979 ## Node.js `package.json` field definitions
981 This section describes the fields used by the Node.js runtime. Other tools (such
982 as [npm](https://docs.npmjs.com/creating-a-package-json-file)) use
983 additional fields which are ignored by Node.js and not documented here.
985 The following fields in `package.json` files are used in Node.js:
987 * [`"name"`][] - Relevant when using named imports within a package. Also used
989 * [`"main"`][] - The default module when loading the package, if exports is not
990 specified, and in versions of Node.js prior to the introduction of exports.
991 * [`"packageManager"`][] - The package manager recommended when contributing to
993 * [`"type"`][] - The package type determining whether to load `.js` files as
995 * [`"exports"`][] - Package exports and conditional exports. When present,
997 * [`"imports"`][] - Package imports, for use by modules within the package
1001 <!-- YAML
1003 - v13.1.0
1004 - v12.16.0
1006 - version:
1007 - v13.6.0
1008 - v12.16.0
1009 pr-url: https://github.com/nodejs/node/pull/31002
1010 description: Remove the `--experimental-resolve-self` option.
1011 -->
1017 "name": "package-name"
1026 [self-reference][] a package using its name.
1029 <!-- YAML
1031 -->
1053 <!-- YAML
1055 -->
1057 > Stability: 1 - Experimental
1063 "packageManager": "<package manager name>@<version>"
1071 Node.js.
1073 This field is currently experimental and needs to be opted-in; check the
1077 <!-- YAML
1080 - version:
1081 - v13.2.0
1082 - v12.17.0
1083 pr-url: https://github.com/nodejs/node/pull/29866
1084 description: Unflag `--experimental-modules`.
1085 -->
1089 The `"type"` field defines the module format that Node.js uses for all
1093 `package.json` file contains a top-level field `"type"` with a value of
1109 node my-app.js # Runs as ES module
1121 // my-app.js, part of the same example as above
1129 <!-- YAML
1132 - version:
1133 - v14.13.0
1134 - v12.20.0
1135 pr-url: https://github.com/nodejs/node/pull/34718
1137 - version:
1138 - v13.7.0
1139 - v12.16.0
1140 pr-url: https://github.com/nodejs/node/pull/31008
1142 - version:
1143 - v13.7.0
1144 - v12.16.0
1145 pr-url: https://github.com/nodejs/node/pull/31001
1146 description: Remove the `--experimental-conditional-exports` option.
1147 - version:
1148 - v13.2.0
1149 - v12.16.0
1150 pr-url: https://github.com/nodejs/node/pull/29978
1152 -->
1164 [self-reference][] to its own name. It is supported in Node.js 12+ as an
1176 <!-- YAML
1178 - v14.6.0
1179 - v12.19.0
1180 -->
1189 "node": "dep-node-native",
1190 "default": "./dep-polyfill.js"
1194 "dep-node-native": "^1.0.0"
1211 [Node.js documentation for this section]: https://github.com/nodejs/node/blob/HEAD/doc/api/packages…
1218 [`--no-addons` flag]: cli.md#cli_no_addons
1220 [`esm`]: https://github.com/standard-things/esm#readme
1223 [self-reference]: #packages_self_referencing_a_package_using_its_name