UNPKG

5.79 kBMarkdownView Raw
1[npm]: https://img.shields.io/npm/v/@rollup/plugin-alias
2[npm-url]: https://www.npmjs.com/package/@rollup/plugin-alias
3[size]: https://packagephobia.now.sh/badge?p=@rollup/plugin-alias
4[size-url]: https://packagephobia.now.sh/result?p=@rollup/plugin-alias
5
6[![npm][npm]][npm-url]
7[![size][size]][size-url]
8[![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com)
9
10# @rollup/plugin-alias
11
12🍣 A Rollup plugin for defining aliases when bundling packages.
13
14## Alias 101
15
16Suppose we have the following `import` defined in a hypothetical file:
17
18```javascript
19import batman from '../../../batman';
20```
21
22This 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` with `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.
23
24```javascript
25import batman from 'batman';
26```
27
28If this seems familiar to Webpack users, it should. This is plugin mimics the `resolve.extensions` and `resolve.alias` functionality in Webpack.
29
30## Requirements
31
32This plugin requires an [LTS](https://github.com/nodejs/Release) Node version (v8.0.0+) and Rollup v1.20.0+.
33
34## Install
35
36Using npm:
37
38```console
39npm install @rollup/plugin-alias --save-dev
40# or
41yarn add -D @rollup/plugin-alias
42```
43
44## Usage
45
46Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:
47
48```js
49import alias from '@rollup/plugin-alias';
50
51module.exports = {
52 input: 'src/index.js',
53 output: {
54 dir: 'output',
55 format: 'cjs'
56 },
57 plugins: [
58 alias({
59 entries: [
60 { find: 'utils', replacement: '../../../utils' },
61 { find: 'batman-1.0.0', replacement: './joker-1.5.0' }
62 ]
63 })
64 ]
65};
66```
67
68Then call `rollup` either via the [CLI](https://www.rollupjs.org/guide/en/#command-line-reference) or the [API](https://www.rollupjs.org/guide/en/#javascript-api). If the build produces any errors, the plugin will write a 'alias' character to stderr, which should be audible on most systems.
69
70## Options
71
72### `customResolver`
73
74Type: `Function | Object`<br>
75Default: `null`
76
77Instructs the plugin to use an alternative resolving algorithm, rather than the Rollup's resolver. Please refer to the [Rollup documentation](https://rollupjs.org/guide/en/#resolveid) for more information about the `resolveId` hook. For a detailed example, see: [Custom Resolvers](#custom-resolvers).
78
79### `entries`
80
81Type: `Object | Array[...Object]`<br>
82Default: `null`
83
84Specifies an `Object`, or an `Array` of `Object`, which defines aliases used to replace values in `import` or `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](#regular-expression-aliases) matching.
85
86#### `Object` Format
87
88The `Object` format allows specifying aliases as a key, and the corresponding value as the actual `import` value. For example:
89
90```js
91alias({
92 entries: {
93 utils: '../../../utils',
94 'batman-1.0.0': './joker-1.5.0'
95 }
96});
97```
98
99#### `Array[...Object]` Format
100
101The `Array[...Object]` format allows specifying aliases as objects, which can be useful for complex key/value pairs.
102
103```js
104entries: [
105 { find: 'utils', replacement: '../../../utils' },
106 { find: 'batman-1.0.0', replacement: './joker-1.5.0' }
107];
108```
109
110## Regular Expression Aliases
111
112Regular Expressions can be used to search in a more distinct and complex manner. e.g. To perform partial replacements via sub-pattern matching.
113
114To remove something in front of an import and append an extension, use a pattern such as:
115
116```js
117{ find:/^i18n\!(.*)/, replacement: '$1.js' }
118```
119
120This would be useful for loaders, and files that were previously transpiled via the AMD module, to properly handle them in rollup as internals.
121
122To replace extensions with another, a pattern like the following might be used:
123
124```js
125{ find:/^(.*)\.js$/, replacement: '$1.alias' }
126```
127
128This would replace the file extension for all imports ending with `.js` to `.alias`.
129
130## Resolving algorithm
131
132This 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](https://www.npmjs.com/package/@rollup/plugin-node-resolve) in your setup.
133
134## Custom Resolvers
135
136The `customResolver` option can be leveraged to provide separate module resolution for an individual alias.
137
138Example:
139
140```javascript
141// rollup.config.js
142import alias from '@rollup/plugin-alias';
143import resolve from '@rollup/plugin-node-resolve';
144
145const customResolver = resolve({
146 extensions: ['.mjs', '.js', '.jsx', '.json', '.sass', '.scss']
147});
148const projectRootDir = path.resolve(__dirname);
149
150export default {
151 // ...
152 plugins: [
153 alias({
154 entries: [
155 {
156 find: 'src',
157 replacement: path.resolve(projectRootDir, 'src')
158 // OR place `customResolver` here. See explanation below.
159 }
160 ],
161 customResolver
162 }),
163 resolve()
164 ]
165};
166```
167
168In 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 `src`. The `customResolver` option can be passed inside each `entries` item for granular control over resolving allowing each alias a preferred resolver.
169
170## Meta
171
172[CONTRIBUTING](/.github/CONTRIBUTING.md)
173
174[LICENSE (MIT)](/LICENSE)