Command Line Interface

Ryan Zimmerman edited this page Jan 3, 2017 · 18 revisions

The command line interface allows you to do most of the things you'd do with the JavaScript API.

First, install rollup as a global module:

npm install -g rollup

(Alternatively, if you're using the rollup command in the context of an npm run script, you can install it as a devDependency for each project, using npm i -D rollup.)

Run rollup -h or rollup --help to view usage instructions.

Usage

rollup [options] <entry file>
  • -v, --version – show version number
  • -c, --config - Use this config file (if argument is used but value is unspecified, defaults to rollup.config.js)
  • -w, --watch – Watch files in bundle and rebuild on changes
  • -i, --input – input (alternative to <entry file>)
  • -o, --output – output (if absent, prints to stdout. See note 1)
  • -f, --format – the output format (see format)
  • -e, --external – comma-separated list of module IDs to exclude (see external)
  • -g, --globals – comma-separated list of id:name pairs (see globals, and note 2)
  • -n, --name – name of bundle in UMD/IIFE output (see moduleName)
  • -u, --id – ID for AMD module (default is anonymous) (see moduleId)
  • -m, --sourcemap – generate sourcemap (-m inline for inline map)
  • --no-strict – disable 'use strict' in generated code
  • --no-indent – disable indentation
  • --environment <values> – settings passed to config file
  • --no-conflict – generate a noConflict method for UMD globals
  • --intro – content to insert at top of bundle (inside wrapper)
  • --outro – content to insert at end of bundle (inside wrapper)
  • --banner – content to insert at top of bundle (outside wrapper)
  • --footer – content to insert at end of bundle (outside wrapper)

Notes

  1. When piping to stdout, only inline sourcemaps are permitted
  2. Any IDs included with the --globals option are automatically added as --external modules

Examples

# create a self-executing bundle...
rollup --format iife -- src/app.js > build/app.js

# ...with inline sourcemaps:
rollup -f iife --sourcemap inline -- src/app.js > build/app.js

# create a bundle with dependencies on jQuery and Angular,
# with a sourcemap in a separate file
rollup -f iife --globals jquery:jQuery,angular:ng \
  -i src/app.js -o build/app.js -m build/app.js.map

# passing values via `process.env`
rollup -c --environment INCLUDE_DEPS,BUILD:production

If using the -c or --config option, the config file should look something like:

import babel from 'rollup-plugin-babel';

export default {
  entry: 'src/main.js',
  plugins: [ babel() ],
  format: 'umd'
};

If using the --environment option, values are available via process.env:

// using the example above
process.env.INCLUDE_DEPS === 'true' // always a string
process.env.BUILD === 'production'

Note: Using rollup-plugin-babel requires installing a babel preset and some setup. See https://github.com/rollup/rollup-plugin-babel#configuring-babel for more details.

Using a config file

Most options can be specified via the command line directly, but you may prefer to use a 'config file' if you're using plugins, or if you want to set options programmatically.

To use a config file, use the --config or -c option:

# by default, rollup.config.js in the
# current directory is used...
rollup -c

# ...but you can specify a particular file...
rollup -c myotherconfig.js

# ...or a package installed via npm – in this
# case Rollup will look for either `awesome-plugins`
# or `rollup-config-awesome-plugins`
rollup -c node:awesome-plugins

The config file itself is simply a JavaScript module:

import buble from 'rollup-plugin-buble';

export default {
  entry: 'src/main.js',
  dest: 'dist/bundle.js',
  format: 'umd',
  plugins: [ buble() ]
};

(You can also use require() and module.exports syntax if you prefer.)

Any options specified via the command line will override the equivalent options in the config file – so in the example above, rollup -c -f cjs -o dist/bundle.cjs.js would write a CommonJS file to dist/bundle.cjs.js.

Targets

A config file can have multiple targets, enabling you to generate (for example) a CommonJS build, a UMD build and an ES build from the same bundle, without duplicating work:

import buble from 'rollup-plugin-buble';

export default {
  entry: 'src/main.js',
  plugins: [ buble() ],
  targets: [
    { dest: 'dist/bundle.cjs.js', format: 'cjs' },
    { dest: 'dist/bundle.umd.js', format: 'umd' },
    { dest: 'dist/bundle.es.js', format: 'es' },
  ]
};