🍣 A Rollup plugin for defining aliases when bundling packages.
Suppose we have the following
import defined in a hypothetical file:
This probably doesn't look too bad on its own. But consider that may not be the only instance in your codebase, and that after a refactor this might be incorrect. With this plugin in place, you can alias
batman for readability and maintainability. In the case of a refactor, only the alias would need to be changed, rather than navigating through the codebase and changing all imports.
If this seems familiar to Webpack users, it should. This is plugin mimics the
resolve.alias functionality in Webpack.
This plugin requires an LTS Node version (v8.0.0+) and Rollup v1.20.0+.
npm install @rollup/plugin-alias --save-dev# oryarn add -D @rollup/plugin-alias
rollup.config.js configuration file and import the plugin:
;moduleexports =input: 'src/index.js'output:dir: 'output'format: 'cjs'plugins:;
Function | Object
Instructs the plugin to use an alternative resolving algorithm, rather than the Rollup's resolver. Please refer to the Rollup documentation for more information about the
resolveId hook. For a detailed example, see: Custom Resolvers.
Object | Array[...Object]
Object, or an
Object, which defines aliases used to replace values in
require statements. With either format, the order of the entries is important, in that the first defined rules are applied first. This option also supports Regular Expression Alias matching.
Object format allows specifying aliases as a key, and the corresponding value as the actual
import value. For example:
Array[...Object] format allows specifying aliases as objects, which can be useful for complex key/value pairs.
entries:find: 'utils' replacement: '../../../utils'find: 'batman-1.0.0' replacement: './joker-1.5.0';
Regular Expression Aliases
Regular Expressions can be used to search in a more distinct and complex manner. e.g. To perform partial replacements via sub-pattern matching.
To remove something in front of an import and append an extension, use a pattern such as:
find:/^i18n\!/ replacement: '$1.js'
This would be useful for loaders, and files that were previously transpiled via the AMD module, to properly handle them in rollup as internals.
To replace extensions with another, a pattern like the following might be used:
find:/^\.js$/ replacement: '$1.alias'
This would replace the file extension for all imports ending with
This plugin uses resolver plugins specified for Rollup and eventually Rollup default algorithm. If you rely on Node specific features, you probably want @rollup/plugin-node-resolve in your setup.
customResolver option can be leveraged to provide separate module resolution for an individual alias.
// rollup.config.js;;const customResolver =;const projectRootDir = path;// ...plugins:;
In the example above the alias
src is used, which uses the
node-resolve algorithm for files aliased with
src, by passing the
customResolver option. The
resolve() plugin is kept separate in the plugins list for other files which are not aliased with
customResolver option can be passed inside each
entries item for granular control over resolving allowing each alias a preferred resolver.