Getting started

Introduction

Rollup bundles ES modules into a single file or chunks. It tree-shakes unused code and uses plugins for JSON, CommonJS, Babel, and minification.

Install locally

Terminal

npm install --save-dev rollup

Check version

npx rollup --version

Use npx for local commands without a global install.

See: Installing Rollup locally

Bundle from the CLI

rollup src/main.js -o bundle.js -f es

-o sets the output file; -f selects the format.

See: Quick start

Use a config file

rollup.config.mjs

export default {
  input: 'src/main.js',
  output: { file: 'dist/bundle.js', format: 'es' }
}

Terminal

rollup -c
rollup --config rollup.config.prod.mjs

rollup -c reads rollup.config.mjs; --config selects another file.

See: Configuration files

Watch files

rollup -c -w

Rebuild on source changes while the process runs.

See: Command line flags

Output

Single file

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'es',
    sourcemap: true
  }
}

file names one bundle; sourcemap emits a .map beside it.

See: output.file

Multiple outputs

export default {
  input: 'src/main.js',
  output: [
    { dir: 'dist/es', format: 'es' },
    { dir: 'dist/cjs', format: 'cjs' }
  ]
}

Rollup needs output.dir when it writes more than one chunk.

See: output.dir

Multiple entries

export default {
  input: {
    main: 'src/main.js',
    admin: 'src/admin.js'
  },
  output: { dir: 'dist', format: 'es' }
}

Each entry name becomes a chunk in dist/.

See: input

Output formats

FormatDescription
esES modules (default)
cjsCommonJS
iifeBrowser script
umdUniversal modules
amdAMD modules
systemSystemJS modules

See: output.format

Dependencies

Keep packages external

export default {
  input: 'src/main.js',
  external: ['lodash'],
  output: { file: 'dist/bundle.js', format: 'es' }
}

external leaves matching imports out of the bundle.

See: external

Map externals to globals

export default {
  input: 'src/main.js',
  external: ['jquery'],
  output: {
    file: 'dist/bundle.js',
    format: 'iife',
    name: 'app',
    globals: { jquery: '$' }
  }
}

globals maps external IDs to browser globals for iife builds.

See: output.globals

Build behaviour

Tree-shaking

export default {
  input: 'src/main.js',
  treeshake: 'smallest',
  output: { dir: 'dist', format: 'es' }
}

smallest drops more code but assumes no side effects.

See: treeshake

Watch config

export default {
  input: 'src/main.js',
  output: { dir: 'dist', format: 'es' },
  watch: {
    include: 'src/**',
    exclude: 'node_modules/**',
    buildDelay: 300,
    clearScreen: false
  }
}

Apply with rollup -c -w.

See: watch

Plugins

JSON files

import json from '@rollup/plugin-json'

export default {
  input: 'src/main.js',
  plugins: [json()],
  output: { dir: 'dist', format: 'es' }
}

Import .json files as modules.

See: @rollup/plugin-json

Node modules

import { nodeResolve } from '@rollup/plugin-node-resolve'

export default {
  input: 'src/main.js',
  plugins: [nodeResolve()],
  output: { dir: 'dist', format: 'es' }
}

Resolve bare imports from node_modules.

See: @rollup/plugin-node-resolve

CommonJS modules

import { nodeResolve } from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'

export default {
  input: 'src/main.js',
  plugins: [nodeResolve(), commonjs()],
  output: { dir: 'dist', format: 'es' }
}

Put commonjs() before Babel when both plugins are used.

See: @rollup/plugin-commonjs

Babel

import { babel } from '@rollup/plugin-babel'

export default {
  input: 'src/main.js',
  plugins: [
    babel({
      babelHelpers: 'bundled',
      presets: ['@babel/preset-env']
    })
  ],
  output: { dir: 'dist', format: 'es' }
}

Set babelHelpers explicitly; bundled inlines helpers.

See: @rollup/plugin-babel

Minify with terser

import terser from '@rollup/plugin-terser'

export default {
  input: 'src/main.js',
  plugins: [terser()],
  output: { dir: 'dist', format: 'es' }
}

Run terser() last so it minifies the finished bundle.

See: @rollup/plugin-terser

Also see

0 Comments for this cheatsheet. Write yours!