A set of utility functions commonly used by Rollup plugins
npm install @rollup/pluginutils[npm]: https://img.shields.io/npm/v/@rollup/pluginutils
[npm-url]: https://www.npmjs.com/package/@rollup/pluginutils
[size]: https://packagephobia.now.sh/badge?p=@rollup/pluginutils
[size-url]: https://packagephobia.now.sh/result?p=@rollup/pluginutils
[![npm][npm]][npm-url]
[![size][size]][size-url]
A set of utility functions commonly used by 🍣 Rollup plugins.
The plugin utils require an LTS Node version (v14.0.0+) and Rollup v1.20.0+.
Using npm:
``console`
npm install @rollup/pluginutils --save-dev
`js`
import utils from '@rollup/pluginutils';
//...
Available utility functions are listed below:
_Note: Parameter names immediately followed by a ? indicate that the parameter is optional._
Adds an extension to a module ID if one does not exist.
Parameters: (filename: String, ext?: String)
Returns:
`js
import { addExtension } from '@rollup/pluginutils';
export default function myPlugin(options = {}) {
return {
resolveId(code, id) {
// only adds an extension if there isn't one already
id = addExtension(id); // foo -> foo.js, foo.js -> foo.js
id = addExtension(id, '.myext'); // -> foo.myext, foo.js -> foo.js
}
};
}
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.
Parameters: (ast: Node, propertyName?: String)
Returns:
See @rollup/plugin-inject or @rollup/plugin-commonjs for an example of usage.
`js
import { attachScopes } from '@rollup/pluginutils';
import { walk } from 'estree-walker';
export default function myPlugin(options = {}) {
return {
transform(code) {
const ast = this.parse(code);
let scope = attachScopes(ast, 'scope');
walk(ast, {
enter(node) {
if (node.scope) scope = node.scope;
if (!scope.contains('foo')) {
// foo is not defined, so if we encounter it,`
// we assume it's a global
}
},
leave(node) {
if (node.scope) scope = scope.parent;
}
});
}
};
}
Constructs a filter function which can be used to determine whether or not certain modules should be operated upon.
Parameters: (include?:
Returns:
#### include and exclude
Type: String | RegExp | Array[...String|RegExp]
A valid picomatch pattern, or array of patterns. If options.include is omitted or has zero length, filter will return true by default. Otherwise, an ID must match one or more of the picomatch patterns, and must not match any of the options.exclude patterns.
Note that picomatch patterns are very similar to minimatch patterns, and in most use cases, they are interchangeable. If you have more specific pattern matching needs, you can view this comparison table to learn more about where the libraries differ.
#### options
##### resolve
Type: String | Boolean | null
Optionally resolves the patterns against a directory other than process.cwd(). If a String is specified, then the value will be used as the base directory. Relative paths will be resolved against process.cwd() first. If false, then the patterns will not be resolved against any directory. This can be useful if you want to create a filter for virtual module names.
#### Usage
`js
import { createFilter } from '@rollup/pluginutils';
export default function myPlugin(options = {}) {
// assume that the myPlugin accepts options of options.include and options.exclude
var filter = createFilter(options.include, options.exclude, {
resolve: '/my/base/dir'
});
return {
transform(code, id) {
if (!filter(id)) return;
// proceed with the transformation...
}
};
}
`
Transforms objects into tree-shakable ES Module imports.
Parameters: (data: Object, options: DataToEsmOptions)
Returns:
#### data
Type: Object
An object to transform into an ES module.
#### options
Type: DataToEsmOptions
_Note: Please see the TypeScript definition for complete documentation of these options_
#### Usage
`js
import { dataToEsm } from '@rollup/pluginutils';
const esModuleSource = dataToEsm(
{
custom: 'data',
to: ['treeshake']
},
{
compact: false,
indent: '\t',
preferConst: true,
objectShorthand: true,
namedExports: true,
includeArbitraryNames: false
}
);
/*
Outputs the string ES module source:
export const custom = 'data';
export const to = ['treeshake'];
export default { custom, to };
*/
`
Extracts the names of all assignment targets based upon specified patterns.
Parameters: (param: Node)
Returns:
#### param
Type: Node
An acorn AST Node.
#### Usage
`js
import { extractAssignedNames } from '@rollup/pluginutils';
import { walk } from 'estree-walker';
export default function myPlugin(options = {}) {
return {
transform(code) {
const ast = this.parse(code);
walk(ast, {
enter(node) {
if (node.type === 'VariableDeclarator') {
const declaredNames = extractAssignedNames(node.id);
// do something with the declared names
// e.g. for const {x, y: z} = ... => declaredNames = ['x', 'z']`
}
}
});
}
};
}
Constructs a RegExp that matches the exact string specified. This is useful for plugin hook filters.
Parameters: (str: String | Array[...String], flags?: String)
Returns:
#### Usage
`js
import { exactRegex } from '@rollup/pluginutils';
exactRegex('foobar'); // /^foobar$/
exactRegex(['foo', 'bar']); // /^(?:foo|bar)$/
exactRegex('foo(bar)', 'i'); // /^foo\(bar\)$/i
`
Constructs a bundle-safe identifier from a String.
Parameters: (str: String)
Returns:
#### Usage
`js
import { makeLegalIdentifier } from '@rollup/pluginutils';
makeLegalIdentifier('foo-bar'); // 'foo_bar'
makeLegalIdentifier('typeof'); // '_typeof'
`
Converts path separators to forward slash.
Parameters: (filename: String)
Returns:
#### Usage
`js
import { normalizePath } from '@rollup/pluginutils';
normalizePath('foo\\bar'); // 'foo/bar'
normalizePath('foo/bar'); // 'foo/bar'
`
Constructs a RegExp that matches a value that has the specified prefix. This is useful for plugin hook filters.
Parameters: (str: String | Array[...String], flags?: String)
Returns:
#### Usage
`js
import { prefixRegex } from '@rollup/pluginutils';
prefixRegex('foobar'); // /^foobar/
prefixRegex(['foo', 'bar']); // /^(?:foo|bar)/
prefixRegex('foo(bar)', 'i'); // /^foo\(bar\)/i
`
Constructs a RegExp that matches a value that has the specified suffix. This is useful for plugin hook filters.
Parameters: (str: String | Array[...String], flags?: String)
Returns:
#### Usage
`js
import { suffixRegex } from '@rollup/pluginutils';
suffixRegex('foobar'); // /foobar$/
suffixRegex(['foo', 'bar']); // /(?:foo|bar)$/
suffixRegex('foo(bar)', 'i'); // /foo\(bar\)$/i
``