Rollup bundling
Bazel

Rollup bundling


Overview

The versions of Rollup and Uglify are controlled by the Bazel toolchain. You do not need to install them into your project.


write_rollup_config

write_rollup_config(ctx, plugins, root_dir, filename, output_format, additional_entry_points)

Generate a rollup config file.

This is also used by the ng_rollup_bundle and ng_package rules in @angular/bazel.

Returns: The rollup config file. See https://rollupjs.org/guide/en#configuration-files

Attributes

ctx

Unknown; Required

Bazel rule execution context

plugins

List of strings; Optional

extra plugins (defaults to []) See the ng_rollup_bundle in @angular/bazel for example of usage.

root_dir

Unknown; Optional

root directory for module resolution (defaults to None)

filename

String; Optional

output filename pattern (defaults to _%s.rollup.conf.js)

output_format

String; Optional

passed to rollup output.format option, e.g. "umd"

additional_entry_points

List of strings; Optional

additional entry points for code splitting


run_rollup

run_rollup(ctx, sources, config, output)

Creates an Action that can run rollup on set of sources.

This is also used by ng_package and ng_rollup_bundle rules in @angular/bazel.

Returns: the sourcemap output file

Attributes

ctx

Unknown; Required

Bazel rule execution context

sources

Unknown; Required

JS sources to rollup

config

Unknown; Required

rollup config file

output

Unknown; Required

output file


run_uglify

run_uglify(ctx, input, output, debug, comments, config_name, in_source_map)

Runs uglify on an input file.

This is also used by https://github.com/angular/angular.

Returns: The sourcemap file

Attributes

ctx

Unknown; Required

Bazel rule execution context

input

Unknown; Required

input file

output

Unknown; Required

output file

debug

Boolean; Optional; Default is False

if True then output is beautified (defaults to False)

comments

Boolean; Optional; Default is True

if True then copyright comments are preserved in output file (defaults to True)

config_name

Unknown; Optional

allows callers to control the name of the generated uglify configuration, which will be _[config_name].uglify.json in the package where the target is declared

in_source_map

Unknown; Optional

sourcemap file for the input file, passed to the "--source-map content=" option of rollup.


run_sourcemapexplorer

run_sourcemapexplorer(ctx, js, map, output)

Runs source-map-explorer to produce an HTML visualization of the sourcemap.

Attributes

ctx

Unknown; Required

bazel rule execution context

js

Unknown; Required

Javascript bundle

map

Unknown; Required

sourcemap from the bundle back to original sources

output

Unknown; Required

file where the HTML report is written


rollup_bundle

rollup_bundle(name, deps, srcs, additional_entry_points, entry_point, global_name, globals, license_banner, node_modules)

Produces several bundled JavaScript files using Rollup and Uglify.

Load it with load("@build_bazel_rules_nodejs//:defs.bzl", "rollup_bundle")

It performs this work in several separate processes:

  1. Call rollup on the original sources
  2. Downlevel the resulting code to es5 syntax for older browsers
  3. Minify the bundle with Uglify, possibly with pretty output for human debugging.

The default output of a rollup_bundle rule is the non-debug-minified es5 bundle.

However you can request one of the other outputs with a dot-suffix on the target's name. For example, if your rollup_bundle is named my_rollup_bundle, you can use one of these labels:

To request the ES2015 syntax (e.g. class keyword) without downleveling or minification, use the :my_rollup_bundle.es6.js label. To request the ES5 downleveled bundle without minification, use the :my_rollup_bundle.js label To request the debug-minified es5 bundle, use the :my_rollup_bundle.min_debug.js label. To request a UMD-bundle, use the :my_rollup_bundle.umd.js label.

You can also request an analysis from source-map-explorer by buildng the :my_rollup_bundle.explore.html label. However this is currently broken for rollup_bundle ES5 mode because we use tsc for downleveling and it doesn't compose the resulting sourcemaps with an input sourcemap. See https://github.com/bazelbuild/rules_nodejs/issues/175

For debugging, note that the rollup.config.js and uglify.config.json files can be found in the bazel-bin folder next to the resulting bundle.

An example usage can be found in https://github.com/bazelbuild/rules_nodejs/tree/master/internal/e2e/rollup

Attributes

name

Name; Required

A unique name for this rule.

deps

List of labels; Optional; Default is []

Other rules that produce JavaScript outputs, such as ts_library.

srcs

List of labels; Optional; Default is []

JavaScript source files from the workspace. These can use ES2015 syntax and ES Modules (import/export)

additional_entry_points

List of strings; Optional; Default is []

Additional entry points of the application for code splitting, passed as the input to rollup. These should be a path relative to the workspace root.

    When additional_entry_points are specified, rollup_bundle
    will split the bundle in multiple entry points and chunks.
    There will be a main entry point chunk as well as entry point
    chunks for each additional_entry_point. The file names
    of these entry points will correspond to the file names
    specified in entry_point and additional_entry_points.
    There will also be one or more common chunks that are shared
    between entry points named chunk-<HASH>.js. The number
    of common chunks is variable depending on the code being
    bundled.

    Entry points and chunks will be outputted to folders:
    - <label-name>.cs.es6 // es6
    - <label-name>.cs // es5
    - <label-name>.cs.min // es5 minified
    - <label-name>.cs.min_debug // es5 minified debug

    The following files will be outputted that contain the
    SystemJS boilerplate to map the entry points to their file
    names and load the main entry point:
    flavors:
    - <label-name>.es6.js // es6
    - <label-name>.js // es5
    - <label-name>.min.js // es5 minified
    - <label-name>.min_debug.js // es5 minified debug

    NOTE: additional_entry_points MUST be in the same folder or deeper than
    the main entry_point for the SystemJS boilerplate/entry point to
    be valid. For example, if the main entry_point is
    `src/main` then all additional_entry_points must be under
    `src/**` such as `src/bar` or `src/foo/bar`. Alternate
    additional_entry_points configurations are valid but the
    SystemJS boilerplate/entry point files will not be usable and
    it is up to the user in these cases to handle the SystemJS
    boilerplate manually.

    It is sufficient to load one of these SystemJS boilerplate/entry point
    files as a script in your HTML to load your application
entry_point

String; Required

The starting point of the application, passed as the --input flag to rollup. This should be a path relative to the workspace root.

global_name

String; Optional; Default is ''

A name given to this package when referenced as a global variable. This name appears in the bundle module incantation at the beginning of the file, and governs the global symbol added to the global context (e.g. window) as a side- effect of loading the UMD/IIFE JS bundle.

    Rollup doc: "The variable name, representing your iife/umd bundle, by which other scripts on the same page can access it."

    This is passed to the `output.name` setting in Rollup.
globals

Dictionary mapping strings to string; Optional; Default is {}

A dict of symbols that reference external scripts. The keys are variable names that appear in the program, and the values are the symbol to reference at runtime in a global context (UMD bundles). For example, a program referencing @angular/core should use ng.core as the global reference, so Angular users should include the mapping "@angular/core":"ng.core" in the globals.

license_banner

Label; Optional

A .txt file passed to the banner config option of rollup. The contents of the file will be copied to the top of the resulting bundles. Note that you can replace a version placeholder in the license file, by using the special version 0.0.0-PLACEHOLDER. See the section on stamping in the README.

node_modules

Label; Optional; Default is //:node_modules_none

Dependencies from npm that provide some modules that must be resolved by rollup.

    This attribute is DEPRECATED. As of version 0.13.0 the recommended approach
    to npm dependencies is to use fine grained npm dependencies which are setup
    with the `yarn_install` or `npm_install` rules. For example, in a rollup_bundle
    target that used the `node_modules` attribute,

    ```
    rollup_bundle(
      name = "bundle",
      ...
      node_modules = "//:node_modules",
    )
    ```

    which specifies all files within the `//:node_modules` filegroup
    to be inputs to the `bundle`. Using fine grained npm dependencies,
    `bundle` is defined with only the npm dependencies that are
    needed:

    ```
    rollup_bundle(
      name = "bundle",
      ...
      deps = [
          "@npm//foo",
          "@npm//bar",
          ...
      ],
    )
    ```

    In this case, only the `foo` and `bar` npm packages and their
    transitive deps are includes as inputs to the `bundle` target
    which reduces the time required to setup the runfiles for this
    target (see https://github.com/bazelbuild/bazel/issues/5153).

    The @npm external repository and the fine grained npm package
    targets are setup using the `yarn_install` or `npm_install` rule
    in your WORKSPACE file:

    yarn_install(
      name = "npm",
      package_json = "//:package.json",
      yarn_lock = "//:yarn.lock",
    )