{ } qjs-modules

loaders/packages

Source: lib/loaders/packages.js (JS over registerHooks(), imports only std and os) — exports: resolve, packageResolve, packageImportsResolve, packageExportsResolve, legacyMainResolve, readPackageJson; qjsm only

Node's ESM package resolution (nodejs.org/api/esm.html) as a resolve hook. qjsm preloads it like loaders/node (off with -N), so import 'pkg' finds node_modules/pkg and import.meta.resolve() reports what it finds.

SpecifierResolves through
pkg, pkg/sub, @scope/pkg/subthe nearest node_modules/pkg up from the importer: its "exports", else "main"
#name"imports" of the package.json nearest to the importer
self/subthe importer's own package, by its "name", when it has "exports"
anything elsethe next resolver (relative paths, builtins, QUICKJS_MODULE_PATH)

A bare name that no node_modules holds goes on to the next resolver, so a module on qjsm's search path still loads.

Conditions

"exports" and "imports" objects are read key by key in the package's order, the first key that is an active condition wins. Active: node, import, default, plus every -C name / --conditions=name given to qjsm (Node's flag). Node 23 also has module-sync, Bun has bun instead of module-sync.

"exports": {
  ".": {
    "import": "./dist/codec.mjs",
    "default": "./dist/codec.umd.js"
  },
  "./sub/*": "./dist/sub/*.js",
  "./internal/*": null
}

Behaviour

CaseResult
"exports" string, array or condition objectthe main export (.)
pattern key ./sub/*the longest matching base, * replaced in the target
target nullERR_PACKAGE_PATH_NOT_EXPORTED
array targetthe first that is not an invalid target, a missing file is not skipped (as on Node)
no "exports"main, main.js, main.json, main/index.js, main/index.json, then index.js, index.json (no .node addons)
the filethrough symlinks (realpath); a missing one is returned as is, the load then fails

Errors carry Node's codes and messages: ERR_MODULE_NOT_FOUND, ERR_PACKAGE_PATH_NOT_EXPORTED, ERR_PACKAGE_IMPORT_NOT_DEFINED, ERR_INVALID_MODULE_SPECIFIER, ERR_INVALID_PACKAGE_TARGET, ERR_INVALID_PACKAGE_CONFIG.

The functions behind the hook

They work on paths, not URLs; utilities/resolve-imports.js uses them for directory imports.

import { packageResolve, packageExportsResolve, readPackageJson } from 'loaders/packages';

packageResolve('@sc/pkg/sub', '/app/src/main.js');           // '/app/node_modules/@sc/pkg/s.js'
packageResolve('cond', '/app/src/main.js', ['import']);       // conditions other than node, import
packageResolve('nope', '/app/src/main.js');                   // undefined: no such package
packageExportsResolve('/app/pkg', '.', readPackageJson('/app/pkg').exports);
FunctionReturns
resolve(specifier, context, nextResolve)the hook: { url, shortCircuit: true } or what nextResolve returns
packageResolve(specifier, parent, conditions?)path, or undefined when no package of that name is found
packageImportsResolve(specifier, parent, conditions?)path of a #name import
packageExportsResolve(pkgDir, subpath, exports, conditions?)path of '.' or './sub'
legacyMainResolve(pkgDir, pjson)path of the main file
readPackageJson(dir)the parsed package.json, null when there is none; cached

Tests: tests/unittests/test-loaders-packages.js, expected values recorded from Node 23.11's import.meta.resolve(), which Bun's resolveSync() matches on every package case.

Export list

Generated by utilities/doc-api.js from the loaders_packages dump of utilities/api-surface.sh: 7 members. Edit the text above this block, not the block.

Functions: default(), legacyMainResolve(), packageExportsResolve(), packageImportsResolve(), packageResolve(), readPackageJson(), resolve()