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 |
|
16 | Suppose we have the following `import` defined in a hypothetical file:
|
17 |
|
18 | ```javascript
|
19 | import batman from '../../../batman';
|
20 | ```
|
21 |
|
22 | 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` 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
|
25 | import batman from 'batman';
|
26 | ```
|
27 |
|
28 | If 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 |
|
32 | This plugin requires an [LTS](https://github.com/nodejs/Release) Node version (v8.0.0+) and Rollup v1.20.0+.
|
33 |
|
34 | ## Install
|
35 |
|
36 | Using npm:
|
37 |
|
38 | ```console
|
39 | npm install @rollup/plugin-alias --save-dev
|
40 | # or
|
41 | yarn add -D @rollup/plugin-alias
|
42 | ```
|
43 |
|
44 | ## Usage
|
45 |
|
46 | Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:
|
47 |
|
48 | ```js
|
49 | import alias from '@rollup/plugin-alias';
|
50 |
|
51 | module.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 |
|
68 | Then 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 |
|
74 | Type: `Function | Object`<br>
|
75 | Default: `null`
|
76 |
|
77 | Instructs 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 |
|
81 | Type: `Object | Array[...Object]`<br>
|
82 | Default: `null`
|
83 |
|
84 | Specifies 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 |
|
88 | The `Object` format allows specifying aliases as a key, and the corresponding value as the actual `import` value. For example:
|
89 |
|
90 | ```js
|
91 | alias({
|
92 | entries: {
|
93 | utils: '../../../utils',
|
94 | 'batman-1.0.0': './joker-1.5.0'
|
95 | }
|
96 | });
|
97 | ```
|
98 |
|
99 | #### `Array[...Object]` Format
|
100 |
|
101 | The `Array[...Object]` format allows specifying aliases as objects, which can be useful for complex key/value pairs.
|
102 |
|
103 | ```js
|
104 | entries: [
|
105 | { find: 'utils', replacement: '../../../utils' },
|
106 | { find: 'batman-1.0.0', replacement: './joker-1.5.0' }
|
107 | ];
|
108 | ```
|
109 |
|
110 | ## Regular Expression Aliases
|
111 |
|
112 | Regular Expressions can be used to search in a more distinct and complex manner. e.g. To perform partial replacements via sub-pattern matching.
|
113 |
|
114 | To 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 |
|
120 | This would be useful for loaders, and files that were previously transpiled via the AMD module, to properly handle them in rollup as internals.
|
121 |
|
122 | To replace extensions with another, a pattern like the following might be used:
|
123 |
|
124 | ```js
|
125 | { find:/^(.*)\.js$/, replacement: '$1.alias' }
|
126 | ```
|
127 |
|
128 | This would replace the file extension for all imports ending with `.js` to `.alias`.
|
129 |
|
130 | ## Resolving algorithm
|
131 |
|
132 | 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](https://www.npmjs.com/package/@rollup/plugin-node-resolve) in your setup.
|
133 |
|
134 | ## Custom Resolvers
|
135 |
|
136 | The `customResolver` option can be leveraged to provide separate module resolution for an individual alias.
|
137 |
|
138 | Example:
|
139 |
|
140 | ```javascript
|
141 | // rollup.config.js
|
142 | import alias from '@rollup/plugin-alias';
|
143 | import resolve from '@rollup/plugin-node-resolve';
|
144 |
|
145 | const customResolver = resolve({
|
146 | extensions: ['.mjs', '.js', '.jsx', '.json', '.sass', '.scss']
|
147 | });
|
148 | const projectRootDir = path.resolve(__dirname);
|
149 |
|
150 | export 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 |
|
168 | 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 `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)
|