UNPKG

4.26 kBMarkdownView Raw
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
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```
41
42## Usage
43
44Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:
45
46```js
47import alias from '@rollup/plugin-alias';
48
49module.exports = {
50 input: 'src/index.js',
51 output: {
52 dir: 'output',
53 format: 'cjs'
54 },
55 plugins: [alias({ resolve: ['.jsx', '.js'] })]
56};
57```
58
59Then 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
65Type: `Object | Array[Object]`<br>
66Default: `null`
67
68Specifies 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
72The `Object` format allows specifying aliases as a key, and the corresponding value as the actual `import` value. For example:
73
74```js
75alias({
76 entries: {
77 utils: '../../../utils',
78 'batman-1.0.0': './joker-1.5.0'
79 }
80});
81```
82
83#### `Array[Object]` Format
84
85The `Array[Object]` format allows specifying aliases as objects, which can be useful for complex key/value pairs.
86
87```js
88entries: [
89 { find: 'utils', replacement: '../../../utils' },
90 { find: 'batman-1.0.0', replacement: './joker-1.5.0' }
91];
92```
93
94### `resolve`
95
96Type: `Array[String]`<br>
97Default: `['.js']`
98
99Specifies 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
102alias({ resolve: ['.jsx', '.js'] });
103```
104
105## Regular Expression Aliases
106
107Regular Expressions can be used to search in a more distinct and complex manner. e.g. To perform partial replacements via sub-pattern matching.
108
109To 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
115This would be useful for loaders, and files that were previously transpiled via the AMD module, to properly handle them in rollup as internals.
116
117To replace extensions with another, a pattern like the following might be used:
118
119```js
120{ find:/^(.*)\.js$/, replacement: '$1.wasm' }
121```
122
123This 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)