5.7 KiB
Executable file
@rollup/pluginutils
A set of utility functions commonly used by 🍣 Rollup plugins.
Requirements
This plugin requires an LTS Node version (v8.0.0+) and Rollup v1.20.0+.
Install
Using npm:
npm install @rollup/pluginutils --save-dev
Usage
import utils from '@rollup/pluginutils';
//...
API
Available utility functions are listed below:
Note: Parameter names immediately followed by a ? indicate that the parameter is optional.
addExtension
Adds an extension to a module ID if one does not exist.
Parameters: (filename: String, ext?: String)
Returns: String
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` -> `foo.myext`, `foo.js -> `foo.js`
}
};
}
attachScopes
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: Object
See rollup-plugin-inject or rollup-plugin-commonjs for an example of usage.
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;
}
});
}
};
}
createFilter
Constructs a filter function which can be used to determine whether or not certain modules should be operated upon.
Parameters: (include?: <minmatch>, exclude?: <minmatch>, options?: Object)
Returns: String
include and exclude
Type: String | RegExp | Array[...String|RegExp]
A valid minimatch 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 minimatch patterns, and must not match any of the options.exclude patterns.
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
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...
}
};
}
dataToEsm
Transforms objects into tree-shakable ES Module imports.
Parameters: (data: Object)
Returns: String
data
Type: Object
An object to transform into an ES module.
Usage
import { dataToEsm } from '@rollup/pluginutils';
const esModuleSource = dataToEsm(
{
custom: 'data',
to: ['treeshake']
},
{
compact: false,
indent: '\t',
preferConst: false,
objectShorthand: false,
namedExports: true
}
);
/*
Outputs the string ES module source:
export const custom = 'data';
export const to = ['treeshake'];
export default { custom, to };
*/
extractAssignedNames
Extracts the names of all assignment targets based upon specified patterns.
Parameters: (param: Node)
Returns: Array[...String]
param
Type: Node
An acorn AST Node.
Usage
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']
}
}
});
}
};
}
makeLegalIdentifier
Constructs a bundle-safe identifier from a String.
Parameters: (str: String)
Returns: String
Usage
import { makeLegalIdentifier } from '@rollup/pluginutils';
makeLegalIdentifier('foo-bar'); // 'foo_bar'
makeLegalIdentifier('typeof'); // '_typeof'