rollup-pluginutils

What is rollup-pluginutils?

The rollup-pluginutils package provides utility functions to help in the creation of Rollup plugins. It includes functions for filtering files, creating caches, and other common tasks needed when developing Rollup plugins.

What are rollup-pluginutils's main functionalities?

createFilter

The createFilter function allows you to create a filter function based on include and exclude patterns. This is useful for determining which files should be processed by your plugin.

const { createFilter } = require('rollup-pluginutils');

const filter = createFilter(['**/*.js', '**/*.jsx'], 'node_modules/**');

console.log(filter('src/main.js')); // true
console.log(filter('node_modules/foo.js')); // false

dataToEsm

The dataToEsm function converts a JavaScript object into an ES module export. This is useful for embedding JSON or other data directly into your Rollup bundles.

const { dataToEsm } = require('rollup-pluginutils');

const data = { foo: 'bar' };
const esmCode = dataToEsm(data);

console.log(esmCode); // export default {"foo":"bar"};

attachScopes

The attachScopes function attaches scope information to an AST, which can be useful for analyzing and transforming code.

const { attachScopes } = require('rollup-pluginutils');
const acorn = require('acorn');

const ast = acorn.parse('const x = 1;');
const scope = attachScopes(ast, 'scope');

console.log(scope.contains('x')); // true

Other packages similar to rollup-pluginutils

rollup-plugin-includepaths

The rollup-plugin-includepaths package allows you to specify include paths for your Rollup bundles. It is similar to rollup-pluginutils' createFilter function but focuses specifically on resolving module paths.

rollup-plugin-json

The rollup-plugin-json package allows you to import JSON files into your Rollup bundles. It provides similar functionality to rollup-pluginutils' dataToEsm function but is specialized for JSON files.

rollup-plugin-node-resolve

The rollup-plugin-node-resolve package helps Rollup to find and bundle third-party dependencies in node_modules. While it doesn't directly overlap with rollup-pluginutils, it complements it by resolving module paths that can then be filtered or transformed using rollup-pluginutils.

README

rollup-pluginutils

A set of functions commonly used by Rollup plugins.

Installation

npm install --save rollup-pluginutils

Usage

addExtension

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

This 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.

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

import { createFilter } from 'rollup-pluginutils';

export default function myPlugin ( options = {} ) {
  // `options.include` and `options.exclude` can each be a minimatch
  // pattern, or an array of minimatch patterns, relative to process.cwd()
  var filter = createFilter( options.include, options.exclude );

  return {
    transform ( code, id ) {
      // 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.
      if ( !filter( id ) ) return;

      // proceed with the transformation...
    }
  };
}

If you want to resolve the patterns against a directory other than process.cwd(), you can additionally pass a resolve option:

var filter = createFilter( options.include, options.exclude, {resolve: '/my/base/dir'} )

If resolve is a string, then this value will be used as the base directory. Relative paths will be resolved against process.cwd() first. If resolve is 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.

makeLegalIdentifier

import { makeLegalIdentifier } from 'rollup-pluginutils';

makeLegalIdentifier( 'foo-bar' ); // 'foo_bar'
makeLegalIdentifier( 'typeof' ); // '_typeof'

dataToEsm

Helper for treeshakable data imports

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

Extract the names of all assignment targets from patterns.

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']
          }
        }
      });
    }
  };
}

License

MIT

Changelog

2.8.2

2019-09-13

• Handle optional catch parameter in attachScopes (#70)