Create bare aliases in the imports map in package.json.

• Supports both ESM import and CommonJS require()
• 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! ❤️}

npm i -D alias-imports

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.

Like Node.js, alias-imports supports subpath patterns.

With this configuration, all lodash/* imports will be aliased to ./custom-lodash/*:

{
    "imports": {
        "lodash/*": "./custom-lodash/*"
    }
}

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

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]"
    }
}

node --loader alias-imports ./file.js

Specify the webpack5 condition via the --conditions, -C flag.

node --loader alias-imports -C webpack5 ./file.js

Pass in alias-import/loader to --loader to load the import hook. This will only add alias support to ESM imports.

node --loader alias-imports/loader ./file.js

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

Passing in alias-imports loads both the loader and the require hook:

node --loader alias-imports ./file.js

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

Used to resolve imports in package.json.

• Native aliases in imports must be prefixed with #, whereas aliases with alias-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 to underscore).

• Affects dependency packages as well, not just the current package

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.

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.