README.md
1# rollup-pluginutils
2
3A set of functions commonly used by Rollup plugins.
4
5
6## Installation
7
8```bash
9npm install --save rollup-pluginutils
10```
11
12
13## Usage
14
15### addExtension
16
17```js
18import { addExtension } from 'rollup-pluginutils';
19
20export default function myPlugin ( options = {} ) {
21 return {
22 resolveId ( code, id ) {
23 // only adds an extension if there isn't one already
24 id = addExtension( id ); // `foo` -> `foo.js`, `foo.js -> foo.js`
25 id = addExtension( id, '.myext' ); // `foo` -> `foo.myext`, `foo.js -> `foo.js`
26 }
27 };
28}
29```
30
31
32### attachScopes
33
34This function attaches `Scope` objects to the relevant nodes of an AST. Each `Scope` object has a `scope.contains(name)` method that returns `true` if a given name is defined in the current scope or a parent scope.
35
36See [rollup-plugin-inject](https://github.com/rollup/rollup-plugin-inject) or [rollup-plugin-commonjs](https://github.com/rollup/rollup-plugin-commonjs) for an example of usage.
37
38```js
39import { attachScopes } from 'rollup-pluginutils';
40import { walk } from 'estree-walker';
41
42export default function myPlugin ( options = {} ) {
43 return {
44 transform ( code ) {
45 const ast = this.parse( code );
46
47 let scope = attachScopes( ast, 'scope' );
48
49 walk( ast, {
50 enter ( node ) {
51 if ( node.scope ) scope = node.scope;
52
53 if ( !scope.contains( 'foo' ) ) {
54 // `foo` is not defined, so if we encounter it,
55 // we assume it's a global
56 }
57 },
58 leave ( node ) {
59 if ( node.scope ) scope = scope.parent;
60 }
61 });
62 }
63 };
64}
65```
66
67
68### createFilter
69
70```js
71import { createFilter } from 'rollup-pluginutils';
72
73export default function myPlugin ( options = {} ) {
74 // `options.include` and `options.exclude` can each be a minimatch
75 // pattern, or an array of minimatch patterns, relative to process.cwd()
76 var filter = createFilter( options.include, options.exclude );
77
78 return {
79 transform ( code, id ) {
80 // if `options.include` is omitted or has zero length, filter
81 // will return `true` by default. Otherwise, an ID must match
82 // one or more of the minimatch patterns, and must not match
83 // any of the `options.exclude` patterns.
84 if ( !filter( id ) ) return;
85
86 // proceed with the transformation...
87 }
88 };
89}
90```
91
92If you want to resolve the patterns against a directory other than
93`process.cwd()`, you can additionally pass a `resolve` option:
94
95```js
96var filter = createFilter( options.include, options.exclude, {resolve: '/my/base/dir'} )
97```
98
99If `resolve` is a string, then this value will be used as the base directory.
100Relative paths will be resolved against `process.cwd()` first. If `resolve` is
101`false`, then the patterns will not be resolved against any directory. This can
102be useful if you want to create a filter for virtual module names.
103
104
105### makeLegalIdentifier
106
107```js
108import { makeLegalIdentifier } from 'rollup-pluginutils';
109
110makeLegalIdentifier( 'foo-bar' ); // 'foo_bar'
111makeLegalIdentifier( 'typeof' ); // '_typeof'
112```
113
114### dataToEsm
115
116Helper for treeshakable data imports
117
118```js
119import { dataToEsm } from 'rollup-pluginutils';
120
121const esModuleSource = dataToEsm({
122 custom: 'data',
123 to: ['treeshake']
124}, {
125 compact: false,
126 indent: '\t',
127 preferConst: false,
128 objectShorthand: false,
129 namedExports: true
130});
131/*
132Outputs the string ES module source:
133 export const custom = 'data';
134 export const to = ['treeshake'];
135 export default { custom, to };
136*/
137```
138
139### extractAssignedNames
140
141Extract the names of all assignment targets from patterns.
142
143```js
144import { extractAssignedNames } from 'rollup-pluginutils';
145import { walk } from 'estree-walker';
146
147export default function myPlugin ( options = {} ) {
148 return {
149 transform ( code ) {
150 const ast = this.parse( code );
151
152 walk( ast, {
153 enter ( node ) {
154 if ( node.type === 'VariableDeclarator' ) {
155 const declaredNames = extractAssignedNames(node.id);
156 // do something with the declared names
157 // e.g. for `const {x, y: z} = ... => declaredNames = ['x', 'z']
158 }
159 }
160 });
161 }
162 };
163}
164```
165
166
167## License
168
169MIT
170