Skip to content
Tutorials Center
My learning

Topics

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.

NODE
{
  "imports": {
    "#config": "./src/config.js",
    "#lib/*": "./src/lib/*.js"
  }
}

Try it

Node.js Aliases instead of relative paths

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.

Node.js Conditions and errors

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

NODE
"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 closest package.json above the importing file. A file inside a nested folder with its own package.json uses 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') and import '#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" } with node --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 imports with moduleResolution set to node16, nodenext or bundler.
  • Not the same as path aliases in bundlers or tsconfig paths: those are tool settings that Node.js itself ignores at runtime, while imports works with plain node.