alias-imports
v1.0.0
Published
Create bare aliases in the imports map in package.json
Downloads
8
Readme
alias-imports
Create bare aliases in the imports
map in package.json
.
Features
- Supports both ESM
import
and CommonJSrequire()
- Subpath patterns support
- Conditions support
- Overwrite
import
/require()
s in dependencies
Support this project by ⭐️ starring and sharing it. Follow me to see what other cool projects I'm working on! ❤️
Usage
Declare aliases in the imports
map in package.json
:
{
"imports": {
// Aliases
"lodash": "./custom-lodash.js"
}
}
Then, run your script with the alias-imports
loader:
node --loader alias-imports ./file.js
Whenever lodash
is imported, ./custom-lodash.js
will be loaded.
Subpath patterns
Like Node.js, alias-imports
supports subpath patterns.
With this configuration, all lodash/*
imports will be aliased to ./custom-lodash/*
:
{
"imports": {
"lodash/*": "./custom-lodash/*"
}
}
Conditions
Like Node.js, alias-imports
supports conditions.
With this configuration, lodash
will be aliased to ./custom-lodash.js
by default. But when --conditions underscore
is passed in, it will resolve to underscore
instead:
{
"imports": {
"lodash": {
"underscore": "underscore",
"default": "./custom-lodash.js"
}
}
}
Pass in a condition:
node --loader alias-imports --conditions underscore ./file.js
Examples
Toggle between Webpack 4 & 5
package.json
{
// Setup imports to load webpack4 by default
// and webpack 5 when the webpack5 condition is specified
"imports": {
"webpack": {
"webpack5": "webpack5",
"default": "webpack4"
},
// This entry maps webpack subpaths to webpack4 or webpack5
"webpack/*": {
"webpack5": "webpack5/*",
"default": "webpack4/*"
}
},
// Install Webpack 4 & 5 to webpack4 & webpack5 respectively
"devDependencies": {
"webpack4": "npm:[email protected]",
"webpack5": "npm:[email protected]"
}
}
Load Webpack 4 (default)
node --loader alias-imports ./file.js
Load Webpack 5
Specify the webpack5
condition via the --conditions, -C
flag.
node --loader alias-imports -C webpack5 ./file.js
API
Loader
Pass in alias-import/loader
to --loader
to load the import hook. This will only add alias support to ESM import
s.
node --loader alias-imports/loader ./file.js
Require hook
Pass in alias-import/require
to --require
to load the require hook. This will only add alias support to require()
calls.
node --require alias-import/require ./file.js
Both
Passing in alias-imports
loads both the loader and the require hook:
node --loader alias-imports ./file.js
Debugging
Set the DEBUG_ALIAS_IMPORTS
environment variable to see which imports
aliases are being resolved by whom.
DEBUG_ALIAS_IMPORTS=1 node --loader alias-imports ./file.js
Dependencies
resolve-pkg-maps
Used to resolve imports
in package.json
.
FAQ
How is it different from native imports
?
Native aliases in
imports
must be prefixed with#
, whereas aliases withalias-imports
don't.Because this loader allows you to create unprefixed aliases, they can be used to overwrite import paths (e.g.
lodash
can point tounderscore
).Affects dependency packages as well, not just the current package
When should I use this instead of native imports
?
In general, you should use native imports
when possible. If you're creating a new alias, prefer to use the #
prefix.
However, if you're trying to overwrite an import path in a dependency package (e.g. lodash
to underscore
), you can use this package to achieve that.
Can I use this in published packages?
Published packages should not use this because it relies on the consumer to start the Node.js process with the alias-imports
loader.
However, it can be used in application codebases to overwrite import paths in dependencies.