.. | ||
dist | ||
LICENSE | ||
package.json | ||
README.md |
resolve-pkg-maps
Utils to resolve package.json
subpath & conditional exports
/imports
in resolvers.
Implements the ESM resolution algorithm. Tested against Node.js for accuracy.
Support this project by ⭐️ starring and sharing it. Follow me to see what other cool projects I'm working on! ❤️
Usage
Resolving exports
utils/package.json
{
// ...
"exports": {
"./reverse": {
"require": "./file.cjs",
"default": "./file.mjs"
}
},
// ...
}
import { resolveExports } from 'resolve-pkg-maps'
const [packageName, packageSubpath] = parseRequest('utils/reverse')
const resolvedPaths: string[] = resolveExports(
getPackageJson(packageName).exports,
packageSubpath,
['import', ...otherConditions]
)
// => ['./file.mjs']
Resolving imports
package.json
{
// ...
"imports": {
"#supports-color": {
"node": "./index.js",
"default": "./browser.js"
}
},
// ...
}
import { resolveImports } from 'resolve-pkg-maps'
const resolvedPaths: string[] = resolveImports(
getPackageJson('.').imports,
'#supports-color',
['node', ...otherConditions]
)
// => ['./index.js']
API
resolveExports(exports, request, conditions)
Returns: string[]
Resolves the request
based on exports
and conditions
. Returns an array of paths (e.g. in case a fallback array is matched).
exports
Type:
type Exports = PathOrMap | readonly PathOrMap[]
type PathOrMap = string | PathConditionsMap
type PathConditionsMap = {
[condition: string]: PathConditions | null
}
The exports
property value in package.json
.
request
Type: string
The package subpath to resolve. Assumes a normalized path is passed in (eg. repeating slashes //
).
It should not start with /
or ./
.
Example: if the full import path is some-package/subpath/file
, the request is subpath/file
.
conditions
Type: readonly string[]
An array of conditions to use when resolving the request. For reference, Node.js's default conditions are ['node', 'import']
.
The order of this array does not matter; the order of condition keys in the export map is what matters instead.
Not all conditions in the array need to be met to resolve the request. It just needs enough to resolve to a path.
resolveImports(imports, request, conditions)
Returns: string[]
Resolves the request
based on imports
and conditions
. Returns an array of paths (e.g. in case a fallback array is matched).
imports
Type:
type Imports = {
[condition: string]: PathOrMap | readonly PathOrMap[] | null
}
type PathOrMap = string | Imports
The imports
property value in package.json
.
request
Type: string
The request resolve. Assumes a normalized path is passed in (eg. repeating slashes //
).
Note: In Node.js, imports resolutions are limited to requests prefixed with
#
. However, this package does not enforce that requirement in case you want to add custom support for non-prefixed entries.
conditions
Type: readonly string[]
An array of conditions to use when resolving the request. For reference, Node.js's default conditions are ['node', 'import']
.
The order of this array does not matter; the order of condition keys in the import map is what matters instead.
Not all conditions in the array need to be met to resolve the request. It just needs enough to resolve to a path.
Errors
ERR_PACKAGE_PATH_NOT_EXPORTED
- If the request is not exported by the export map
ERR_PACKAGE_IMPORT_NOT_DEFINED
- If the request is not defined by the import map
ERR_INVALID_PACKAGE_CONFIG
- If an object contains properties that are both paths and conditions (e.g. start with and without
.
) - If an object contains numeric properties
ERR_INVALID_PACKAGE_TARGET
- If a resolved exports path is not a valid path (e.g. not relative or has protocol)
- If a resolved path includes
..
ornode_modules
- If a resolved path is a type that cannot be parsed
FAQ
Why do the APIs return an array of paths?
exports
/imports
supports passing in a fallback array to provide fallback paths if the previous one is invalid:
{
"exports": {
"./feature": [
"./file.js",
"./fallback.js"
]
}
}
Node.js's implementation picks the first valid path (without attempting to resolve it) and throws an error if it can't be resolved. Node.js's fallback array is designed for forward compatibility with features (e.g. protocols) that can be immediately/inexpensively validated:
{
"exports": {
"./core-polyfill": ["std:core-module", "./core-polyfill.js"]
}
}
However, Webpack and TypeScript have deviated from this behavior and attempts to resolve the next path if a path cannot be resolved.
By returning an array of matched paths instead of just the first one, the user can decide which behavior to adopt.
How is it different from resolve.exports
?
resolve.exports
only resolves exports
, whereas this package resolves both exports
& imports
. This comparison will only cover resolving exports
.
-
Despite it's name,
resolve.exports
handles more than justexports
. It takes in the entirepackage.json
object to handle resolving.
and self-references. This package only acceptsexports
/imports
maps frompackage.json
and is scoped to only resolving what's defined in the maps. -
resolve.exports
accepts the full request (e.g.foo/bar
), whereas this package only accepts the requested subpath (e.g.bar
). -
resolve.exports
only returns the first result in a fallback array. This package returns an array of results for the user to decide how to handle it. -
resolve.exports
supports subpath folder mapping (deprecated in Node.js v16 & removed in v17) but seems to have a bug. This package does not support subpath folder mapping because Node.js has removed it in favor of using subpath patterns. -
Neither resolvers rely on a file-system
This package also addresses many of the bugs in resolve.exports
, demonstrated in this test.