Node.js Reference ยท Module Systems
The package.json imports field
Reference for the imports field in package.json: define private #-prefixed specifiers that map to files or packages, with conditions, patterns and the errors Node.js raises.
The imports field of a package.json defines private aliases that only code inside that package can use. Every alias starts with #, for example #db or #utils/format. In place of long relative paths such as ../../../lib/db.js, files import #db, and Node.js maps the alias to the real file.
Unlike exports, which describes what the package offers to the outside, imports is for the package's own source. Because the names start with #, they can never clash with an npm package. An alias can also point to an external package, and to different targets depending on the environment.
{
"imports": {
"#config": "./src/config.js",
"#lib/*": "./src/lib/*.js"
}
}
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
"imports": { "#name": "./path/inside/package.js", "#name/*": "./path/*.js", "#dep": "some-package", "#env": { "node": "./node.js", "default": "./other.js" } }
| Part | Description |
|---|---|
| Key | Must start with #. A * in the key makes it a pattern, as in exports. A key of just # or one starting #/ is invalid. |
Target ./... |
A file inside the package, relative to the package.json that defines the field. |
| Target bare name | An external package or a built-in written without the node: prefix (fs), resolved like an ordinary import from that file. Unlike exports, this is allowed. |
| Condition object | Chooses a target by condition (import, require, node, default, and custom ones set with --conditions). See Conditional exports. |
Errors: ERR_PACKAGE_IMPORT_NOT_DEFINED when no key matches the # specifier, ERR_INVALID_MODULE_SPECIFIER for a malformed one, and ERR_INVALID_PACKAGE_TARGET for a bad target value.
Usage notes
- Scope: the nearest
package.json. Node.js looks for the field in the closestpackage.jsonabove the importing file. A file inside a nested folder with its ownpackage.jsonuses that one. - Private by design. No other package can use your
#names, and they do not appear in the published API, so you can change them freely. - Works in both module systems.
require('#config')andimport '#config'both use the field; with conditions you can send each to a different file. - Handy for environment swaps, for example
"#db": { "test": "./src/db-fake.js", "default": "./src/db.js" }withnode --conditions=test. - No extension guessing. Targets must be exact file names (or patterns that end in an extension), as in
exports. - Editors and TypeScript need to understand the field too. TypeScript resolves
importswithmoduleResolutionset tonode16,nodenextorbundler. - Not the same as path aliases in bundlers or
tsconfigpaths: those are tool settings that Node.js itself ignores at runtime, whileimportsworks with plainnode.