1 | [cover]: https://codecov.io/gh/rollup/plugins/alias/branch/master/graph/badge.svg
|
2 | [cover-url]: https://codecov.io/gh/rollup/plugins/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 | [![cover][cover]][cover-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 | ```
|
41 |
|
42 | ## Usage
|
43 |
|
44 | Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:
|
45 |
|
46 | ```js
|
47 | import alias from '@rollup/plugin-alias';
|
48 |
|
49 | module.exports = {
|
50 | input: 'src/index.js',
|
51 | output: {
|
52 | dir: 'output',
|
53 | format: 'cjs'
|
54 | },
|
55 | plugins: [alias({ resolve: ['.jsx', '.js'] })]
|
56 | };
|
57 | ```
|
58 |
|
59 | 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.
|
60 |
|
61 | ## Options
|
62 |
|
63 | ### `entries`
|
64 |
|
65 | Type: `Object | Array[Object]`<br>
|
66 | Default: `null`
|
67 |
|
68 | 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.
|
69 |
|
70 | #### `Object` Format
|
71 |
|
72 | The `Object` format allows specifying aliases as a key, and the corresponding value as the actual `import` value. For example:
|
73 |
|
74 | ```js
|
75 | alias({
|
76 | entries: {
|
77 | utils: '../../../utils',
|
78 | 'batman-1.0.0': './joker-1.5.0'
|
79 | }
|
80 | });
|
81 | ```
|
82 |
|
83 | #### `Array[Object]` Format
|
84 |
|
85 | The `Array[Object]` format allows specifying aliases as objects, which can be useful for complex key/value pairs.
|
86 |
|
87 | ```js
|
88 | entries: [
|
89 | { find: 'utils', replacement: '../../../utils' },
|
90 | { find: 'batman-1.0.0', replacement: './joker-1.5.0' }
|
91 | ];
|
92 | ```
|
93 |
|
94 | ### `resolve`
|
95 |
|
96 | Type: `Array[String]`<br>
|
97 | Default: `['.js']`
|
98 |
|
99 | Specifies an array of file extensions to use when attempting to resolve an `import` (or `require`). The extensions will be tried in the order they are specified. By default, this option is configured to resolve only files that have the `.js` extension. For example; to resolve both `JSX` and `JS` files:
|
100 |
|
101 | ```js
|
102 | alias({ resolve: ['.jsx', '.js'] });
|
103 | ```
|
104 |
|
105 | ## Regular Expression Aliases
|
106 |
|
107 | Regular Expressions can be used to search in a more distinct and complex manner. e.g. To perform partial replacements via sub-pattern matching.
|
108 |
|
109 | To remove something in front of an import and append an extension, use a pattern such as:
|
110 |
|
111 | ```js
|
112 | { find:/^i18n\!(.*)/, replacement: '$1.js' }
|
113 | ```
|
114 |
|
115 | This would be useful for loaders, and files that were previously transpiled via the AMD module, to properly handle them in rollup as internals.
|
116 |
|
117 | To replace extensions with another, a pattern like the following might be used:
|
118 |
|
119 | ```js
|
120 | { find:/^(.*)\.js$/, replacement: '$1.wasm' }
|
121 | ```
|
122 |
|
123 | This would replace the file extension for all imports ending with `.js` to `.wasm`.
|
124 |
|
125 | ## Meta
|
126 |
|
127 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
128 |
|
129 | [LICENSE (MIT)](./LICENSE)
|