Start to work with rollup.js to pack JS files

rollup.js is a module bundler for JavaScript. It compiles small piece of JavaScript modules spreading in different files into a single larger standardized ES code file. This post will show some entry level usage for this library.

Introduction

Normally a bundler tool would compile a few small JavaScript files into a single JavaScript so that web browser can read, parse and render it properly. A bundler tool may be needed because of a few reasons:

• Some early stage browsers don't understand modules, the modularized JS codes need to be packed into standard JS code so that browser can understand
• The module mechanism of NodeJS is not compatible with web browser, they need to be bundled so that they can be compatible with web browsers.
• It is more efficient for web browser to load single large JS file than load multiple smaller JS files.

Currently the most frequently used bundling tool is webpack, it is powerful but also difficult to use and configure and is criticized by lots of developers.

The initial idea of developing rollup.js is to provide a simple and easy to use tool for bundling/packing ES modules. It doesn't necessarily need any configuration and can be used directly. Later it starts to support bundle/pack CommonJS modules as well, however this requires more configurations and is not better than webpack in this regard. 

Hence it is recommended to use rollup.js to bundle ES modules only, it is not recommended to use rollup.js to bundle CommonJS modules.

Installation

This post will use global mode to install rollup. 

$ npm install --global rollup

You can also use it without installation by replacing rollup with npm rollup in all following commands. To check help, can run below command.

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

Examples

This example will try to show packing two simple scripts: lib script add.js and entry-point script main.s.

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

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

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

There are two exported functions in above script: addPi() and addE().

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

console.log(addPi(10));

main.js imports the lib function addPi() from add.js.

Now using rollup to pack the scripts.

$ rollup main.js

Only entry-point script is needed when packing the scripts, rollup will automatically include the dependent scripts. The output of packing will be like:

const PI = 3.14;

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

console.log(addPi(10));

It becomes standard JS code, the import and export statements are gone. These can be understood by browsers. One thing to note is that addE() is not packed as it is not used anywhere. This feature is called tree-shaking. 

If wanna output the result into a different file, can add --file option.

$ rollup main.js --file bundle.js

Above command will output the result to bundle.js.

Points to take note

If there are multiple entry-point scripts, add each file as parameters and specify --dir to output results into a directory.

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

There will be files m1.js, m2.js in dist directory.

If wanna compact the output result, can add --compact option.

$ rollup main.js --compact

Another method is to use a dedicated compacting tool.

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

Rollup supports configuration file as well, 

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

Use below command to load configuration file.

$ rollup -c

Output CommonJS module

Rollup also supports converting ES module to CommonJS module, just add an option --format cjs.

$ rollup add.js --format cjs

The output would be

'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: 打包工具 rollup.js 入门教程 - 阮一峰的网络日志 (ruanyifeng.com)