Rollup: CommonJS to UMD

rollup.js

Whereas Webpack is great for building apps, Rollup is great for building libraries.

Rollup supports ES modules out of the box. However, to support CommonJS, the following plugins are required:

• @rollup/plugin-commonjs
• @rollup/plugin-node-resolve

Prerequisites

• Node.js
• npm

Setup

Install rollup:

$ npm install rollup

Create the entry file index.js:

$ echo "export default 'Hello, world!'" > index.js

Initialize package.json:

$ npm init --yes

Add the build script to package.json:

The script compiles index.js to dist/bundle.js.

Run the build script:

$ npm run build

To find that you got the error:

Error: You must specify "output.format", which can be one of "amd", "cjs", "system", "esm", "iife" or "umd".

Output Format

Rollup expects an output format. Here are the general guidelines:

• For browsers, use iife (Immediately Invoked Function Expression)
• For Node.js, use cjs (CommonJS)
• For both browsers and Node.js, use umd (Universal Module Definition)

To generate a UMD bundle with MyModuleName as the export name:

$ npx rollup index.js --file dist/bundle.js --format umd --name 'MyModuleName'

Load with script

Load the module in a browser using a <script> tag:

Load with AMD

Load the module in a browser using AMD (Asynchronous Module Definition):

Load with CommonJS

Load the module in Node.js using CommonJS:

$ node
> const MyModuleName = require('./dist/bundle');
> console.log(MyModuleName);
Hello, world!

Config

Instead of passing the options via the CLI (command-line interface), you can specify them in the configuration file rollup.config.js.

Create the file rollup.config.js:

$ touch rollup.config.js

Add the config:

Update the build script in package.json to use the config file:

To give the config file a name other than the default, you’ll need to specify the custom file location:

$ npx rollup --config my.config.js

Plugins

CommonJS

To use CommonJS syntax, install @rollup/plugin-commonjs:

$ npm install @rollup/plugin-commonjs

Add the plugin to the rollup config:

Now refactor index.js:

After rebuilding the bundle, loading it with script, AMD, or CommonJS should continue to work:

$ npm run build
$ open script.html
$ open amd.html
$ node -p "require('./dist/bundle')"
Hello, world!

Node Resolve

Let’s say you want to use lodash in index.js:

$ npm install lodash

In order for rollup to locate 3rd party modules in node_modules, you need to install @rollup/plugin-node-resolve:

$ npm install @rollup/plugin-node-resolve

Add the plugin to the rollup config:

Build the bundle to verify it still works:

$ npm run build
$ node -p "require('./dist/bundle')"
Hello, world!

If you want the module resolution to respect the “browser” field in package.json, you can set the option resolve({ browser: true }).

Terser

To minify your bundle with rollup v2, use terser.

Install rollup-plugin-terser:

$ npm install rollup-plugin-terser

Add the plugin to the rollup config:

Use an environment variable to determine whether you want to build a minified or unminified bundle:

Set the environment variable before you run the build command:

$ NODE_ENV=production npm run build

Alternatively, this can be done in the package.json build script:

Uglify

To minify the bundle with rollup v1, use UglifyJS.

Install rollup-plugin-uglify:

$ npm install rollup-plugin-uglify

Add the plugin to the rollup config:

Now you can build an uglified bundle:

$ npm run build
$ node -p "require('./dist/bundle')"
Hello, world!

JSON

To import JSON files, install @rollup/plugin-json:

$ npm install @rollup/plugin-json

Add the plugin to the rollup config similarly to how it was done for the other plugins:

Resources

To learn more about Rollup, check out the official documentation.

This article was originally published on remarkablemark.org on July 12, 2019.