Rollup.js overview

Use rollup as a bundler to build web apps

view on github

why rollup

  • compiles ES6+ JS code using ESM modules to a standalone bundle :
    1. bundles can be any flavor of module management system (amd, cjs, es, iife, umd, system)
    2. source files are statically analyzed, unused functions/variables are removed (treeshaking)

compile source files

  • for the node_modules imports to be resolved as well, the dependencies have to be installed
  • compile and resolve all imports to a single js file containing a self-executing function ('iife')
npx rollup source/main.js --file build/bundle.js --format iife
  • multiple bundles can be produced from multiple inputs (if rollup.config.js exports an array of configurations)

modules publication

  • when publishing ES6+ libraries that may run in pre ES6 environments ("type": "commonjs" in package.json) :
    1. use rollup to compile the library to any legacy module management system
    2. set the "main" property of package.json to point to the compiled version

plugins

  • @rollup/plugin-commonjs : required to turn imported commonJS dependencies to ESM (probably for further processing)
  • @rollup/plugin-node-resolve : required to bundle code located in dependencies (uses node module resolution algorithm)
  • @rollup/plugin-babel : required for transpiling the bundles into pre ES6 code

limitations

  • important note : babel should NOT process the core-js polyfills (set up the babel plugin exclude option)
  • the semantics used by rollup to convert esm modules to cjs are :
    1. add names as properties of module.exports if an esm namespace is exported :
      • module.exports.something = something;
    2. if a default esm export if present :
      • module.exports = <whatever is exported as default in esm>
  • see output.interop option for details on the above

desigining plugins

  1. a rollup plugin has to be distributed as a package which exports a function that :
    • can be called with plugin specific options
    • will return a plugin object
  2. a rollup plugin is an object with one or more :
    • properties
    • build hooks
    • output generation hooks
  3. hooks are functions that are called at various stages of the build process and allow the plugin code to interact with it :
    • by affecting the build process execution
    • by providing information about it
    • by modifying the build files once the build process is complete
  4. the different kinds of hooks are :
hook type comment
sync/async async hooks return promises resolving to a value of the same type as their input value, otherwise they are sync
first if several plugins implement this hook, they are run sequentially until one returns a value other than null or undefined
sequential if several plugins implement this hook, they are run in the specified plugin order (if such a hook is async, subsequent ones will wait until the current one's resolution)
parallel if several plugins implement this hook, they are run in the specified plugin order (if such a hook is async, subsequent ones execute in paralle of the current one)

  1. build hooks list (plugin-located placeholder functions for code that will execute at various stage of the build process ...) :

    • buildEnd
    • buildStart
    • closeWatcher
    • load
    • moduleParsed
    • options
    • resolveDynamicImport
    • resolveId
    • shouldTransformCachedModule
    • transform
    • watchChange

  2. details on build hooks :

    • see build hooks execution sequence
    • build hooks process entries
    • build hooks may be called multiple times, each time on a different module, as rollup builds the dependency graph
    • build hooks are mainly concerned with locating, providing and transforming input files before treeshaking is performed
    • build hooks are dependant on one another for execution a la systemd units

  3. ouptut generation hooks :

    • augmentChunkHash
    • banner
    • closeBundle
    • footer
    • generateBundle
    • intro
    • outputOptions
    • outro
    • renderChunk
    • renderDynamicImport
    • renderError
    • renderStart
    • resolveFileUrl
    • resolveImportMeta
    • writeBundle

  4. details on ouptut generation hooks :

    • see output generation hooks execution sequence
    • ouptut generation process chunks
    • ouptut generation hooks may be called multiple times, once for each chunk before the actual bundle is rendered
    • ouptut generation build hooks are mainly concerned with providing information about a generated bundle and modifying it after treeshaking is performed
    • ouptut generation hooks are dependant on one another for execution (a la systemd units)

  5. plugin context helpers are functions that can be accessed from inside hooks through ````this``` (hook function thus has to bind to something at runtime)

  6. plugin context helpers list :

    • this.addWatchFile
    • this.emitFile
    • this.error
    • this.getCombinedSourcemap
    • this.getFileName
    • this.getModuleIds
    • this.getModuleInfo
    • this.getWatchFiles
    • this.load
    • this.meta
    • this.parse
    • this.resolve
    • this.setAssetSource
    • this.warn