Getting Started with Rollup.js Packaging Tool

Getting Started with Rollup.js Packaging Tool

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


The role of the bundler is to combine multiple JavaScript scripts into a single script for the browser to use.

Browsers require script packaging for three main reasons.

  • Early browsers did not support modules, and large web projects could only be combined into a single script before execution.
  • The module mechanism of Node.js is not compatible with browsers and must be handled by packaging tools.
  • It is better for browsers to load one large script than to load multiple small scripts.

Currently, the most commonly used packaging tool is Webpack. It has powerful functions, but it is difficult to learn and use, and has been criticized all the time.

The development intention of rollup.js is to create an easy-to-use ES module packaging tool that can be used directly without configuration. This, it does.

Later, after continuous development, it can also package CommonJS modules. However, this requires complex configuration, which is actually not much simpler than Webpack.

Therefore, it is recommended to only use rollup.js for packaging ES modules, so that it can take full advantage of it. Below you will see how simple that is.

If your project uses CommonJS modules, rollup.js is not recommended and has little advantage.


This article uses the global installation of rollup.js.

$ npm install --global rollup

However, you can also use it directly without installation, that is rollup, replace all of the following commands with npx rollup.

For the first time, you can run the following command to see the help.

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


Next, we use rollup.js to package two simple scripts: the library file add.js and the entry script main.js.

// 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 utility functions addPi() and addE().

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


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

Next, package it with rollup.js.

$ rollup main.js

When packaging, you only need to give the entry script main.js, and rollup will automatically package the dependencies into it.

The packaging result is output to the screen by default.

const PI = 3.14;

function addPi(x) {
  return x + PI;


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

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

Because of the above two points, the code output by rollup is very clean and smaller than other packaging tools.

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

$ rollup main.js --file bundle.js

The above command will save the packaging result to bundle.js.

Notes on use

(1) If there are multiple entry scripts, fill in their file names in turn, and use parameters --dir to specify the output directory.

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

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

(2) The parameter --format iife will put the packaged result in an automatic execution function.

$ rollup main.js --format iife

(3) If you want to minimize the code after packaging, use parameters --compact.

$ rollup main.js --compact

Another way is to use specialized tools.

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

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

(4) rollup supports the use of configuration files (rollup.config.js), and the parameters are written in it. The following is an example.

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

The parameter -c enables the configuration file.

$ rollup -c

I don’t recommend using configuration files, it adds extra complexity. By default, command line arguments are sufficient and easier to read.

Convert to CommonJS module

Finally, rollup also supports the conversion of ES modules into CommonJS modules, --format cjs just use parameters.

$ rollup add.js --format cjs

The converted CommonJS module, the code is as follows.

'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;