broccoli-rollup

What is broccoli-rollup?

broccoli-rollup is a Broccoli plugin that allows you to use Rollup to bundle your JavaScript files. It integrates the Rollup module bundler into the Broccoli build pipeline, enabling you to take advantage of Rollup's features such as tree-shaking, code-splitting, and plugin support within a Broccoli-based build system.

What are broccoli-rollup's main functionalities?

Basic Usage

This example demonstrates the basic usage of broccoli-rollup. It sets up a Rollup build that takes an input file 'src/main.js' and outputs a bundled file 'bundle.js' in CommonJS format. It also includes plugins for resolving node modules and converting CommonJS modules to ES6.

const Rollup = require('broccoli-rollup');
const nodeResolve = require('rollup-plugin-node-resolve');
const commonjs = require('rollup-plugin-commonjs');

const tree = new Rollup('src', {
  rollup: {
    input: 'src/main.js',
    output: {
      file: 'bundle.js',
      format: 'cjs'
    },
    plugins: [
      nodeResolve(),
      commonjs()
    ]
  }
});

module.exports = tree;

Tree-shaking

This example shows how to enable tree-shaking with broccoli-rollup. Tree-shaking is a feature that eliminates dead code from the final bundle, making it smaller and more efficient. The 'treeshake' option is set to true in the Rollup configuration.

const Rollup = require('broccoli-rollup');

const tree = new Rollup('src', {
  rollup: {
    input: 'src/main.js',
    output: {
      file: 'bundle.js',
      format: 'es'
    },
    treeshake: true
  }
});

module.exports = tree;

Code-splitting

This example demonstrates how to use code-splitting with broccoli-rollup. Code-splitting allows you to split your code into multiple bundles, which can be loaded on demand. The 'experimentalCodeSplitting' option is enabled in the Rollup configuration.

const Rollup = require('broccoli-rollup');

const tree = new Rollup('src', {
  rollup: {
    input: 'src/main.js',
    output: [
      {
        dir: 'dist',
        format: 'es'
      }
    ],
    experimentalCodeSplitting: true
  }
});

module.exports = tree;

Other packages similar to broccoli-rollup

rollup

Rollup is a module bundler for JavaScript which compiles small pieces of code into something larger and more complex, such as a library or application. While broccoli-rollup integrates Rollup into the Broccoli build system, Rollup itself can be used standalone or with other build systems.

webpack

Webpack is a popular module bundler that can handle not only JavaScript but also assets like CSS, images, and fonts. It offers a rich plugin ecosystem and advanced features like hot module replacement. Compared to broccoli-rollup, Webpack is more feature-rich and versatile but can be more complex to configure.

parcel

Parcel is a web application bundler that offers a zero-configuration setup. It automatically handles common tasks like code-splitting, hot module replacement, and asset bundling. Parcel is easier to set up compared to broccoli-rollup but may not offer the same level of customization.

README

broccoli-rollup

A broccoli plugin that uses rollup.js on its input.

Usage

Basic

// Brocfile.js
import rollup from 'broccoli-rollup';

export default () =>
  rollup('lib', {
    // nodeModulesPath: string Defaults to process.cwd()
    rollup: {
      input: 'index.js',
      output: {
        file: 'bundle.js',
        format: 'es',
      },
    },
  });

Code Splitting

// Brocfile.js
import rollup from 'broccoli-rollup';

export default () =>
  rollup('lib', {
    // nodeModulesPath: string Defaults to process.cwd()
    rollup: {
      input: 'index.js',
      output: {
        dir: 'chunks',
        format: 'es',
      },
    },
  });

Multiple Output

// Brocfile.js
import rollup from 'broccoli-rollup';

export default () =>
  rollup('lib', {
    // nodeModulesPath: string Defaults to process.cwd()
    rollup: {
      input: 'index.js',
      output: [
        {
          file: 'my-lib.amd.js',
          format: 'amd',
        },
        {
          file: 'my-lib.iife.js',
          name: 'MyLib',
          format: 'iife',
        },
      ],
    },
  });

Notes and Caveats

Broccoli is designed around immutable input and although rollup does expose enough in the build output for us to write it to disk, this doesn't work with the onwrite plugin hook and requires a significant amount of code to get feature parity with rollup's buildOutput.write(outputOptions).

We use the following build flow to achieve compatibility and feature parity with rollup's cli while still adhering to broccoli's immutable input constraints.

1. sync node.inputPaths[0] to ${node.cachePath}/build
2. symlink options.nodeModulesPath to ${node.cachePath}/node_modules
3. change the working directory to ${node.cachePath}/build (rollup doesn't allow this to be passed in and plugins may also the use cwd)
4. run rollup
5. restore the working directory
6. sync ${node.cachePath}/build to node.outputPath for all files that are different from the input.

If you have any plugins that require hard-coded paths into node_modules, please note that node_modules is symlinked above the build path.

So instead of doing node_modules/x you need to do ../node_modules/x.

Changelog

5.0.0

Breaking Changes

• Updated rollup to 2.x. See https://github.com/rollup/rollup/blob/master/CHANGELOG.md#200
• Node 12 now required