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.
- Rollup documentation (rollupjs.org)
- CLI reference (rollupjs.org)
- Configuration options (rollupjs.org)
- Official plugins (github.com)
Install locally
Terminal
npm install --save-dev rollup
Check version
npx rollup --version
Use npx for local commands without a global install.
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
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
| Format | Description |
|---|---|
es | ES modules (default) |
cjs | CommonJS |
iife | Browser script |
umd | Universal modules |
amd | AMD modules |
system | SystemJS 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.
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.
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.
0 Comments for this cheatsheet. Write yours!