rollup.js is a JavaScript packaging tool. This article describes its basic usage.

rollup

1. Introduction

The purpose of the packager tool is to combine multiple JavaScript scripts into a single script for the browser.

Browsers need script packaging for three main reasons.

  1. Early browsers did not support modules, and large web projects could only be merged into a single script before execution.
  2. The module mechanism of Node.js is not compatible with browsers and must be handled for compatibility by packaging tools.
  3. Browsers load one large script with better performance than multiple small scripts.

Currently, the most commonly used packaging tool is Webpack, which is powerful, but difficult to learn and use, and has been criticized.

Webpack vs rollup

rollup.js was developed with the intention of creating an easy-to-use ES module packaging tool that doesn’t need to be configured and is straightforward to use. This it did.

As it evolved, it could also package CommonJS modules. However, this requires complex configuration and is actually not much simpler than Webpack.

So it is recommended that only rollup.js be used to package ES modules so that it can take full advantage of it. As you’ll see below, that’s a very simple thing to do.

If your project uses CommonJS modules, it is not recommended to use rollup.js, there is not much advantage.

2. Installation

This article uses a global installation of rollup.js.

1

$ npm install --global rollup

However, you can also use it directly without installing it. Just replace rollup in all the commands below with npx rollup.

The first time you use it, you can run the following command and check the help.

1
2
3
4


$ rollup --help
# or
$ npx rollup --help

3. Example

Below, two simple scripts are packaged using rollup.js: the library file add.js and the entry script main.js.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// add.js
const PI = 3.14;
const E = 2.718;

export function addPi(x) {
  return x + PI;
}

export function addE(x) {
  return x + E; 
}

In the above code, the module add.js outputs two tool functions addPi() and addE().

1
2
3
4

// main.js
import { addPi } from './add.js';

console.log(addPi(10));

In the above code, the entry script main.js loads the tool function addPi() inside add.js.

Then, it is packaged with rollup.js.

1

$ rollup main.js

To package, simply give the entry script main.js and rollup will automatically package the dependencies.

The result is output to the screen by default.

1
2
3
4
5
6
7

const PI = 3.14;

function addPi(x) {
  return x + PI;
}

console.log(addPi(10));

As you can see, the import and export statements are gone and have been replaced with the original code.

Also, the function addE() is not packaged because it is not used. This feature is called tree-shaking, which means that unused code is automatically removed when packaging.

Because of these two things, rollup outputs very neat code and is smaller than other packaging tools.

Use the parameter -file [FILENAME] to save the result to the specified file.

1

$ rollup main.js --file bundle.js

The above command saves the package results to bundle.js.

4. Notes on use

  1. If there are multiple entry scripts, fill in their filenames in turn and specify the output directory with the parameter --dir.

    1

    $ rollup m1.js m2.js --dir dist

    The above command will generate multiple files in the directory dist, packaged: m1.js, m2.js, and their common dependencies (if any).

  2. The parameter --format iife, will put the packing result inside an auto-execute function.

    1

    $ rollup main.js --format iife

  3. If you want to minimize the code after packaging, use the parameter --compact.

    1

    $ rollup main.js --compact

    Another approach is to use specialized tools.

    1

    $ rollup main.js | uglifyjs --output bundle.js

    The above command is divided into two steps, the first step is to rollup the package, the second step is to uglifyjs for code minimization, and finally write the bundle.js.

  4. rollup supports using config file (rollup.config.js) to write all parameters in it, here is an example.

    1
2
3
4
5
6
7
8

    // rollup.config.js
export default {
input: 'main.js',
output: {
    file: 'bundle.js',
    format: 'es'
}
};

    The -c parameter enables the profile.

    1

    $ rollup -c

    I do not recommend using configuration files, which add additional complexity. The default scenario is that command line parameters are sufficient and easier to read.

5. Converting to CommonJS modules

Finally, rollup also supports converting ES modules to CommonJS modules, using the parameter -format cjs.

1

$ rollup add.js --format cjs

The converted CommonJS module with the following code.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


'use strict';

Object.defineProperty(exports, '__esModule', { value: true });

const PI = 3.14;
const E = 2.718;

function addPi(x) {
  return x + PI;
}

function addE(x) {
  return x + E; 
}

exports.addE = addE;
exports.addPi = addPi;

Reference http://www.ruanyifeng.com/blog/2022/05/rollup.html