Lines Matching full:package
15 description: Add package `"imports"` field.
25 description: Unflag self-referencing a package using its name.
29 Introduce `"exports"` `package.json` field as a more powerful alternative
34 Add support for ES modules using `.js` file extension via `package.json`
40 A package is a folder tree described by a `package.json` file. The package
41 consists of the folder containing the `package.json` file and all subfolders
42 until the next folder containing another `package.json` file, or a folder
45 This page provides guidance for package authors writing `package.json` files
46 along with a reference for the [`package.json`][] fields defined by Node.js.
55 * Files ending in `.js` when the nearest parent `package.json` file contains a
62 where the nearest parent `package.json` file contains no top-level `"type"`
71 * Files ending in `.js` when the nearest parent `package.json` file contains a
77 Package authors should include the [`"type"`][] field, even in packages where
78 all sources are CommonJS. Being explicit about the `type` of the package will
79 future-proof the package in case the default type of Node.js ever changes, and
81 files in the package should be interpreted.
83 ### `package.json` and file extensions
85 Within a package, the [`package.json`][] [`"type"`][] field defines how
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`
90 files within that package as using [ES module][] syntax.
96 // my-app.js, treated as an ES module because there is a package.json
100 // Loaded as ES module since ./startup contains no package.json file,
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
113 the nearest parent `package.json`.
116 nearest parent `package.json`.
122 import 'commonjs-package/src/index.mjs';
127 package:
129 * Within a `"type": "module"` package, Node.js can be instructed to
132 a `"module"` package).
134 * Within a `"type": "commonjs"` package, Node.js can be instructed to
137 `"commonjs"` package).
158 ## Determining package manager
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
165 tool called [Corepack][] that aims to make all package managers transparently
168 By default Corepack won't enforce any specific package manager and will use
171 in your project's `package.json`.
173 ## Package entry points
175 In a package’s `package.json` file, two fields can define entry points for a
176 package: [`"main"`][] and [`"exports"`][]. The [`"main"`][] field is supported
178 the main entry point of the package.
181 package main entry point can be defined while also encapsulating the package,
184 their package.
194 package entry points per environment, including whether the package is
196 both CommonJS and ES Modules in a single package please consult
200 package from using any entry points that are not defined, including the
201 [`package.json`][] (e.g. `require('your-package/package.json')`. **This will
206 entry points so that the package’s public API is well-defined. For example,
208 `feature`, and the `package.json` could use the following `package.exports`:
220 "./package.json": "./package.json"
236 "./package.json": "./package.json"
241 As a last resort, package encapsulation can be disabled entirely by creating an
242 export for the root of the package `"./*": "./*"`. This exposes every file
243 in the package at the cost of disabling the encapsulation and potential tooling
253 To set the main entry point for a package, it is advisable to define both
254 [`"exports"`][] and [`"main"`][] in the package’s [`package.json`][] file:
263 When the [`"exports"`][] field is defined, all subpaths of the package are
269 about package interfaces for tools and when handling semver upgrades for a
270 package. It is not a strong encapsulation since a direct require of any
271 absolute subpath of the package such as
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';
315 package import maps that only apply to import specifiers from within the package
319 disambiguated from package specifiers.
325 // package.json
339 where `import '#dep'` does not get the resolution of the external package
341 file `./dep-polyfill.js` relative to the package in other environments.
358 large numbers of subpaths, this might cause `package.json` bloat and
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
397 patterns since the individual exports for a package can be determined by
399 files within the package. Because `node_modules` paths are forbidden in exports
400 targets, this expansion is dependent on only the files of the package itself.
405 // ./node_modules/es-module-package/package.json
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
465 For example, a package that wants to provide different ES module exports for
469 // package.json
482 * `"import"` - matches when the package is loaded via `import` or
486 * `"require"` - matches when the package is loaded via `require()`. The
526 Defines a package where `require('pkg/feature')` and `import 'pkg/feature'`
542 For example, to define a package that only has dual mode entry points for
577 which would then resolve the `"development"` condition in package imports and
635 ### Self-referencing a package using its name
645 description: Unflag self-referencing a package using its name.
648 Within a package, the values defined in the package’s
649 `package.json` [`"exports"`][] field can be referenced via the package’s name.
650 For example, assuming the `package.json` is:
653 // package.json
655 "name": "a-package",
663 Then any module _in that package_ can reference an export in the package itself:
667 import { something } from 'a-package'; // Imports "something" from ./main.mjs.
670 Self-referencing is available only if `package.json` has [`"exports"`][], and
671 will allow importing only what that [`"exports"`][] (in the `package.json`)
672 allows. So the code below, given the previous package, will generate a runtime
679 // the "package.json" "exports" field
681 import { another } from 'a-package/m.mjs';
689 const { something } = require('a-package/foo'); // Loads from ./foo.js.
696 // package.json
698 "name": "@my/package",
710 console.log(require('@my/package'));
721 pattern for package authors to include both CommonJS and ES module JavaScript
722 sources in their package, with `package.json` [`"main"`][] specifying the
723 CommonJS entry point and `package.json` `"module"` specifying the ES module
729 Node.js can now run ES module entry points, and a package can contain both
737 ### Dual package hazard
739 When an application is using a package that provides both CommonJS and ES module
740 sources, there is a risk of certain bugs if both versions of the package get
744 `'pkg/module'`). This is the “dual package hazard,” where two versions of the
745 same package can be loaded within the same runtime environment. While it is
746 unlikely that an application or package would intentionally load both versions
752 If the package main export is a constructor, an `instanceof` comparison of
762 First, the hazard described in the previous section occurs when a package
765 package might instead be written where any version of Node.js receives only
766 CommonJS sources, and any separate ES module sources the package might contain
767 are intended only for other environments such as browsers. Such a package
771 A package might also switch from CommonJS to ES module syntax in a [breaking
773 newest version of the package would only be usable in ES module-supporting
779 1. The package is usable via both `require` and `import`.
780 1. The package is usable in both current Node.js and older versions of Node.js
782 1. The package main entry point, e.g. `'pkg'` can be used by both `require` to
785 1. The package provides named exports, e.g. `import { name } from 'pkg'` rather
787 1. The package is potentially usable in other ES module environments such as
793 Write the package in CommonJS or transpile ES module sources into CommonJS, and
799 // ./node_modules/pkg/package.json
845 * The package is currently written in CommonJS and the author would prefer not
848 * The package has other packages that depend on it, and the end user might
849 install both this package and those other packages. For example a `utilities`
850 package is used directly in an application, and a `utilities-plus` package
854 * The package stores internal state, and the package author would prefer not to
855 refactor the package to isolate its state management. See the next section.
859 version of the package. This could be used via `import 'pkg/module'` by users
862 but doesn’t affect the ES module version (for example, because the package is
866 // ./node_modules/pkg/package.json
879 A [`package.json`][] file can define the separate CommonJS and ES module entry
883 // ./node_modules/pkg/package.json
894 This can be done if both the CommonJS and ES module versions of the package are
896 the package’s management of state is carefully isolated (or the package is
900 versions of the package might get used within an application; for example, the
903 package would be loaded in memory and therefore two separate states would be
906 Aside from writing a stateless package (if JavaScript’s `Math` were a package,
909 CommonJS and ES module instances of the package:
913 package, it would be used like this:
921 The `new` keyword isn’t required; a package’s function can return a new
923 package.
926 CommonJS and ES module versions of the package. For example, if the CommonJS
948 Any plugins that attach to the package’s singleton would need to separately
952 * The package is currently written in ES module syntax and the package author
954 * The package is stateless or its state can be isolated without too much
956 * The package is unlikely to have other public packages that depend on it, or if
957 it does, the package is stateless or has state that need not be shared between
961 execution between the CommonJS and ES module versions of a package.
965 `"./module"`, to point to an all-ES module-syntax version of the package:
968 // ./node_modules/pkg/package.json
979 ## Node.js `package.json` field definitions
982 as [npm](https://docs.npmjs.com/creating-a-package-json-file)) use
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
988 by package managers as the name of the package.
989 * [`"main"`][] - The default module when loading the package, if exports is not
991 * [`"packageManager"`][] - The package manager recommended when contributing to
992 the package. Leveraged by the [Corepack][] shims.
993 * [`"type"`][] - The package type determining whether to load `.js` files as
995 * [`"exports"`][] - Package exports and conditional exports. When present,
996 limits which submodules can be loaded from within the package.
997 * [`"imports"`][] - Package imports, for use by modules within the package
1017 "name": "package-name"
1021 The `"name"` field defines your package’s name. Publishing to the
1023 [certain requirements](https://docs.npmjs.com/files/package.json#name).
1026 [self-reference][] a package using its name.
1041 The `"main"` field defines the script that is used when the [package directory
1049 When a package has an [`"exports"`][] field, this will take precedence over the
1050 `"main"` field when importing the package by name.
1063 "packageManager": "<package manager name>@<version>"
1067 The `"packageManager"` field defines which package manager is expected to be
1069 [supported package managers][], and will ensure that your teams use the exact
1070 same package manager versions without having to install anything else than
1090 `.js` files that have that `package.json` file as their nearest parent.
1093 `package.json` file contains a top-level field `"type"` with a value of
1096 The nearest parent `package.json` is defined as the first `package.json` found
1101 // package.json
1108 # In same folder as preceding package.json
1112 If the nearest parent `package.json` lacks a `"type"` field, or contains
1114 root is reached and no `package.json` is found, `.js` files are treated as
1118 parent `package.json` contains `"type": "module"`.
1122 import './startup.js'; // Loaded as ES module because of package.json
1162 The `"exports"` field allows defining the [entry points][] of a package when
1169 package entry points per environment, including whether the package is
1185 // package.json
1203 This field defines [subpath imports][] for the current package.
1221 [`package.json`]: #packages_node_js_package_json_field_definitions
1226 [supported package managers]: corepack.md#corepack_supported_package_managers