skip to content

In a Node.js application, what does the package.json `imports` field do, and how does `import '#internal/db.js'` get resolved?

level: middleimportance: should knowfreq 25%

answer

  1. hash-prefixed private aliases
  2. nearest package.json decides
  3. targets relative to package root
  4. conditions and patterns work here too
  5. ERR_PACKAGE_IMPORT_NOT_DEFINED

basics

~20 s

The imports field defines private, '#'-prefixed specifiers for code inside one package. Node finds the importing file's nearest package.json, matches '#internal/db.js' against its imports keys and patterns, and resolves the target from the package root, for both import and require().

solid answer

~40 s

`"imports"` is the inward-facing twin of `"exports"`: a map of specifiers starting with `#` that only files inside the package can use. For `import '#internal/db.js'`, Node finds the **nearest `package.json`** above the importing file (stopping at a `node_modules` boundary), looks up `#internal/db.js` as an exact key or a `*` pattern such as `"#internal/*": "./src/internal/*"`, and resolves the target relative to the **package root**, not to the importing file. Targets can also carry conditions, and unlike `"exports"` they may name an external package. It works the same for `require()`. A missing key throws `ERR_PACKAGE_IMPORT_NOT_DEFINED`. In Node 24.14.0 and later, specifiers may also start with `#/`, so a `"#/*": "./src/*"` entry works.

code

javascript · 7 lines
javascript
// /srv/orders/src/routes/orders.js, with the package.json imports map above
import { pool } from '#internal/db.js';
// resolves to /srv/orders/src/internal/db.js (from the package root)

import config from '#config';
// node server.js            -> ./src/config/prod.js
// node -C development ...   -> ./src/config/dev.js

go deeper

for a junior

Recall that imports defines private # aliases inside one package, resolved by Node from the nearest package.json, and that targets start from the package root.

for a middle

Explain the resolution steps: package scope lookup, exact key then pattern match, conditions in key order, ERR_PACKAGE_IMPORT_NOT_DEFINED, and how it differs from exports.

for a senior

Show where it earns its keep in a service: replacing relative-path chains and NODE_PATH, switching config with -C, and keeping other tools' resolution in step.

for a principal

Decide whether a codebase standardises on # aliases, which prefixes are allowed, and how the Node version floor affects using the #/ form.

## The problem it solves In a service with a deep folder tree, internal imports turn into chains like `../../../lib/db.js`. They break on every file move, and older fixes are worse: `NODE_PATH` is ignored by `import`, and symlinks into `node_modules` hide the mapping outside the code. Node's **subpath imports** give the package its own aliases, declared in `package.json` and resolved by Node itself at run time: ```json { "name": "orders-service", "type": "module", "imports": { "#internal/*": "./src/internal/*", "#config": { "development": "./src/config/dev.js", "default": "./src/config/prod.js" } } } ``` ## How Node resolves a '#' specifier When Node sees a specifier that begins with `#`, it skips the `node_modules` walk entirely: 1. It finds the **package scope** of the importing file: the nearest `package.json` in that file's folder or above, without crossing a `node_modules` boundary. 2. It reads that file's `"imports"` field. If there is none, or the key is missing, it throws `ERR_PACKAGE_IMPORT_NOT_DEFINED` (for example `Package import specifier "#db" is not defined in package /app/package.json imported from /app/src/server.js`). 3. It matches the specifier against an exact key first, then against single-`*` pattern keys, preferring the most specific pattern. 4. It resolves the chosen target. A target starting with `./` is resolved from the **package root**; a target that is a bare package name is resolved like any other package, through `node_modules` and that package's own `"exports"`. The specifier `#` alone is invalid, and a target beginning with `../` or `/` is refused with `ERR_INVALID_PACKAGE_TARGET`, so a mapping cannot point outside the package. ## Rules that differ from exports | Aspect | `"exports"` | `"imports"` | |---|---|---| | Who can use it | Anyone importing the package by name | Only files inside the package | | Key prefix | `.` or `./…` | `#…` | | Targets | Must start with `./` | `./…` or an external package name | | Missing key error | `ERR_PACKAGE_PATH_NOT_EXPORTED` | `ERR_PACKAGE_IMPORT_NOT_DEFINED` | Everything else carries over: conditions (`node`, `import`, `require`, `default`, plus any added with `--conditions`) are matched in key order, `*` patterns substitute plain strings, and the target is used exactly as written with no extension probing. ## Where it pays off - **Stable internal paths.** `#internal/db.js` stays valid wherever the importing file moves. - **Environment switches without code changes.** With the `#config` entry above, `node -C development server.js` loads the development config, and a normal start loads the production one. - **Swapping a dependency for a polyfill.** A condition object can point `node` at an installed package and `default` at a local file, which `"exports"` cannot express because its targets must stay inside the package. - **Both loaders.** `require('#internal/db.js')` and `import '#internal/db.js'` resolve through the same map. - **Isolation between packages.** A dependency's own `#` aliases resolve against its own `package.json`, so names never collide with the app's. ## Debugging a '#' specifier When a `#` import fails, check three things in order: 1. **Which `package.json` is in scope.** A nested folder with its own `package.json` (common in monorepos and in test fixtures) becomes the scope for files below it, and its `"imports"` field, or the lack of one, is what Node reads. 2. **Whether the key matches literally.** `#internal/db` does not match a `"#internal/*.js"` pattern, and no extension is added. 3. **Which condition branch was taken.** Resolve the specifier with `import.meta.resolve('#config')` or `require.resolve('#config')` under the same `-C` flags the process uses. ## Version notes and limits Before Node 24.14.0, a specifier starting with `#/` was rejected as invalid, so maps used a word after the hash (`#internal/*`, `#lib/*`). From 24.14.0 the shorter `"#/*": "./src/*"` form, used as `import x from '#/db.js'`, is allowed. Tools that resolve modules without running Node, such as type checkers and bundlers, need their own support or configuration for these aliases; their settings are covered with those tools.

  • Can a file inside a Node.js dependency use the application's `#` imports?
    No. Node resolves a `#` specifier against the nearest `package.json` above the importing file, and the search stops at the `node_modules` boundary. A file inside `node_modules/some-package` therefore sees only that package's own `"imports"` field, so each package's aliases stay private.
  • How does `"imports"` in Node.js differ from importing your own package by its name?
    A self-reference such as `import x from 'orders-service/feature'` only works when the package has `"exports"`, and it can reach only what `"exports"` makes public. `"imports"` maps private `#` names to any file inside the package, or to an external package, without making anything public.

  • An imports target like ./src/db.js resolves relative to the importing file
  • Subpath imports only work with import, not with require()
  • Code outside the package can use its # aliases
  • imports keys can use any prefix, not just #
  • Node resolves # specifiers by walking node_modules folders

Assumes Node.js 24.14.0 or later: that release first allowed subpath imports starting with '#/'; earlier releases reject such specifiers as invalid.