title |
---|
JavaScript API |
Rollup provides a JavaScript API which is usable from Node.js. You will rarely need to use this, and should probably be using the command line API unless you are extending Rollup itself or using it for something esoteric, such as generating bundles programmatically.
The rollup.rollup
function returns a Promise that resolves to a bundle
object with various properties and methods shown here:
const rollup = require('rollup');
// see below for details on the options
const inputOptions = {...};
const outputOptions = {...};
async function build() {
// create a bundle
const bundle = await rollup.rollup(inputOptions);
console.log(bundle.watchFiles); // an array of file names this bundle depends on
// generate code
const { output } = await bundle.generate(outputOptions);
for (const chunkOrAsset of output) {
if (chunkOrAsset.type === 'asset') {
// For assets, this contains
// {
// fileName: string, // the asset file name
// source: string | Buffer // the asset source
// type: 'asset' // signifies that this is an asset
// }
console.log('Asset', chunkOrAsset);
} else {
// For chunks, this contains
// {
// code: string, // the generated JS code
// dynamicImports: string[], // external modules imported dynamically by the chunk
// exports: string[], // exported variable names
// facadeModuleId: string | null, // the id of a module that this chunk corresponds to
// fileName: string, // the chunk file name
// imports: string[], // external modules imported statically by the chunk
// isDynamicEntry: boolean, // is this chunk a dynamic entry point
// isEntry: boolean, // is this chunk a static entry point
// map: string | null, // sourcemaps if present
// modules: { // information about the modules in this chunk
// [id: string]: {
// renderedExports: string[]; // exported variable names that were included
// removedExports: string[]; // exported variable names that were removed
// renderedLength: number; // the length of the remaining code in this module
// originalLength: number; // the original length of the code in this module
// };
// },
// name: string // the name of this chunk as used in naming patterns
// type: 'chunk', // signifies that this is a chunk
// }
console.log('Chunk', chunkOrAsset.modules);
}
}
// or write the bundle to disk
await bundle.write(outputOptions);
}
build();
The inputOptions
object can contain the following properties (see the big list of options for full details on these):
const inputOptions = {
// core input options
external,
input, // required
plugins,
// advanced input options
cache,
inlineDynamicImports,
manualChunks,
onwarn,
preserveModules,
strictDeprecations,
// danger zone
acorn,
acornInjectPlugins,
context,
moduleContext,
preserveSymlinks,
shimMissingExports,
treeshake,
// experimental
experimentalCacheExpiry,
perf
};
The outputOptions
object can contain the following properties (see the big list of options for full details on these):
const outputOptions = {
// core output options
dir,
file,
format, // required
globals,
name,
plugins,
// advanced output options
assetFileNames,
banner,
chunkFileNames,
compact,
entryFileNames,
extend,
externalLiveBindings,
footer,
hoistTransitiveImports,
interop,
intro,
outro,
paths,
sourcemap,
sourcemapExcludeSources,
sourcemapFile,
sourcemapPathTransform,
// danger zone
amd,
dynamicImportFunction,
esModule,
exports,
freeze,
indent,
namespaceToStringTag,
noConflict,
preferConst,
strict
};
Rollup also provides a rollup.watch
function that rebuilds your bundle when it detects that the individual modules have changed on disk. It is used internally when you run Rollup from the command line with the --watch
flag.
const rollup = require('rollup');
const watchOptions = {...};
const watcher = rollup.watch(watchOptions);
watcher.on('event', event => {
// event.code can be one of:
// START — the watcher is (re)starting
// BUNDLE_START — building an individual bundle
// BUNDLE_END — finished building a bundle
// END — finished building all bundles
// ERROR — encountered an error while bundling
});
// stop watching
watcher.close();
The watchOptions
argument is a config (or an array of configs) that you would export from a config file.
const watchOptions = {
...inputOptions,
output: [outputOptions],
watch: {
chokidar,
clearScreen,
exclude,
include
}
};
See above for details on inputOptions
and outputOptions
, or consult the big list of options for info on chokidar
, include
and exclude
.