| |
| |
| <!-- |
| Documentation generated by Skydoc |
| --> |
| <!DOCTYPE html> |
| <html> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width initial-scale=1" /> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| |
| <title>Rollup bundling</title> |
| |
| <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700" type="text/css"> |
| <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"> |
| <link rel="stylesheet" href="https://code.getmdl.io/1.1.1/material.green-light_blue.min.css"> |
| <script defer src="https://code.getmdl.io/1.1.1/material.min.js"></script> |
| <link rel="stylesheet" href="/rules_nodejs/main.css"> |
| </head> |
| <body> |
| <div class="mdl-layout mdl-js-layout mdl-layout--fixed-drawer |
| mdl-layout--fixed-header"> |
| <header class="mdl-layout__header"> |
| <div class="mdl-layout__header-row"> |
| <span class="mdl-layout-title">Rollup bundling</span> |
| </div> |
| </header> |
| <div class="mdl-layout__drawer"> |
| <span class="mdl-layout-title">Bazel</span> |
| <nav class="drawer-nav"> |
| <ul class="drawer-nav"> |
| |
| <li><a href="/rules_nodejs/index.html">Overview</a></li> |
| <li> |
| <a href="/rules_nodejs/common/check_bazel_version.html">Check Bazel version</a> |
| <ul> |
| <li><a href="/rules_nodejs/common/check_bazel_version.html#overview">Overview</a></li> |
| </ul> |
| </li> |
| <li> |
| <a href="/rules_nodejs/history-server/history_server.html">Run history-server</a> |
| <ul> |
| </ul> |
| </li> |
| <li> |
| <a href="/rules_nodejs/http-server/http_server.html">Run http-server</a> |
| <ul> |
| </ul> |
| </li> |
| <li> |
| <a href="/rules_nodejs/jasmine_node_test/jasmine_node_test.html">NodeJS testing</a> |
| <ul> |
| <li><a href="/rules_nodejs/jasmine_node_test/jasmine_node_test.html#overview">Overview</a></li> |
| </ul> |
| </li> |
| <li> |
| <a href="/rules_nodejs/node/node.html">Executing programs</a> |
| <ul> |
| <li><a href="/rules_nodejs/node/node.html#overview">Overview</a></li> |
| <li> |
| <a href="/rules_nodejs/node/node.html#nodejs_binary"> |
| nodejs_binary |
| </a> |
| </li> |
| <li> |
| <a href="/rules_nodejs/node/node.html#nodejs_test"> |
| nodejs_test |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="/rules_nodejs/node/node_repositories.html">Install NodeJS & Yarn</a> |
| <ul> |
| <li><a href="/rules_nodejs/node/node_repositories.html#overview">Overview</a></li> |
| </ul> |
| </li> |
| <li> |
| <a href="/rules_nodejs/npm_install/npm_install.html">Install npm packages</a> |
| <ul> |
| <li><a href="/rules_nodejs/npm_install/npm_install.html#overview">Overview</a></li> |
| </ul> |
| </li> |
| <li> |
| <a href="/rules_nodejs/npm_package/npm_package.html">npm packaging</a> |
| <ul> |
| <li><a href="/rules_nodejs/npm_package/npm_package.html#overview">Overview</a></li> |
| <li> |
| <a href="/rules_nodejs/npm_package/npm_package.html#npm_package"> |
| npm_package |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="/rules_nodejs/rollup/rollup_bundle.html">Rollup bundling</a> |
| <ul> |
| <li><a href="/rules_nodejs/rollup/rollup_bundle.html#overview">Overview</a></li> |
| <li> |
| <a href="/rules_nodejs/rollup/rollup_bundle.html#rollup_bundle"> |
| rollup_bundle |
| </a> |
| </li> |
| </ul> |
| </li> |
| |
| </ul> |
| </nav> |
| </div> |
| |
| <main class="mdl-layout__content"> |
| <div class="page-content"> |
| <h1>Rollup bundling</h1> |
| |
| <nav class="toc"> |
| <h2><a href="#overview">Overview</a></h2> |
| <h2>Rules</h2> |
| <ul> |
| <li><a href="#rollup_bundle">rollup_bundle</a></li> |
| </ul> |
| <h2>Macros</h2> |
| <ul> |
| <li><a href="#write_rollup_config">write_rollup_config</a></li> |
| <li><a href="#run_rollup">run_rollup</a></li> |
| <li><a href="#run_uglify">run_uglify</a></li> |
| <li><a href="#run_sourcemapexplorer">run_sourcemapexplorer</a></li> |
| </ul> |
| </nav> |
| <hr> |
| <h2 id="overview">Overview</h2> |
| <p>The versions of Rollup and Uglify are controlled by the Bazel toolchain. |
| You do not need to install them into your project.</p> |
| |
| <hr> |
| |
| <h2 id="write_rollup_config">write_rollup_config</h2> |
| |
| <pre>write_rollup_config(<a href="#write_rollup_config.ctx">ctx</a>, <a href="#write_rollup_config.plugins">plugins</a>, <a href="#write_rollup_config.root_dir">root_dir</a>, <a href="#write_rollup_config.filename">filename</a>, <a href="#write_rollup_config.output_format">output_format</a>, <a href="#write_rollup_config.additional_entry_points">additional_entry_points</a>)</pre> |
| |
| <p>Generate a rollup config file.</p> |
| <p>This is also used by the ng_rollup_bundle and ng_package rules in @angular/bazel.</p> |
| <p>Returns: |
| The rollup config file. See <a href="https://rollupjs.org/guide/en#configuration-files">https://rollupjs.org/guide/en#configuration-files</a></p> |
| |
| |
| <h3 id="write_rollup_config_args">Attributes</h3> |
| |
| <table class="params-table"> |
| <colgroup> |
| <col class="col-param" /> |
| <col class="col-description" /> |
| </colgroup> |
| <tbody> |
| <tr id="write_rollup_config.ctx"> |
| <td><code>ctx</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>Bazel rule execution context</p> |
| </td> |
| </tr> |
| <tr id="write_rollup_config.plugins"> |
| <td><code>plugins</code></td> |
| <td> |
| <p><code>List of strings; Optional</code></p> |
| <p>extra plugins (defaults to []) |
| See the ng_rollup_bundle in @angular/bazel for example of usage.</p> |
| </td> |
| </tr> |
| <tr id="write_rollup_config.root_dir"> |
| <td><code>root_dir</code></td> |
| <td> |
| <p><code>Unknown; Optional</code></p> |
| <p>root directory for module resolution (defaults to None)</p> |
| </td> |
| </tr> |
| <tr id="write_rollup_config.filename"> |
| <td><code>filename</code></td> |
| <td> |
| <p><code>String; Optional</code></p> |
| <p>output filename pattern (defaults to <code>_%s.rollup.conf.js</code>)</p> |
| </td> |
| </tr> |
| <tr id="write_rollup_config.output_format"> |
| <td><code>output_format</code></td> |
| <td> |
| <p><code>String; Optional</code></p> |
| <p>passed to rollup output.format option, e.g. "umd"</p> |
| </td> |
| </tr> |
| <tr id="write_rollup_config.additional_entry_points"> |
| <td><code>additional_entry_points</code></td> |
| <td> |
| <p><code>List of strings; Optional</code></p> |
| <p>additional entry points for code splitting</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <hr> |
| |
| <h2 id="run_rollup">run_rollup</h2> |
| |
| <pre>run_rollup(<a href="#run_rollup.ctx">ctx</a>, <a href="#run_rollup.sources">sources</a>, <a href="#run_rollup.config">config</a>, <a href="#run_rollup.output">output</a>)</pre> |
| |
| <p>Creates an Action that can run rollup on set of sources.</p> |
| <p>This is also used by ng_package and ng_rollup_bundle rules in @angular/bazel.</p> |
| <p>Returns: |
| the sourcemap output file</p> |
| |
| |
| <h3 id="run_rollup_args">Attributes</h3> |
| |
| <table class="params-table"> |
| <colgroup> |
| <col class="col-param" /> |
| <col class="col-description" /> |
| </colgroup> |
| <tbody> |
| <tr id="run_rollup.ctx"> |
| <td><code>ctx</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>Bazel rule execution context</p> |
| </td> |
| </tr> |
| <tr id="run_rollup.sources"> |
| <td><code>sources</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>JS sources to rollup</p> |
| </td> |
| </tr> |
| <tr id="run_rollup.config"> |
| <td><code>config</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>rollup config file</p> |
| </td> |
| </tr> |
| <tr id="run_rollup.output"> |
| <td><code>output</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>output file</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <hr> |
| |
| <h2 id="run_uglify">run_uglify</h2> |
| |
| <pre>run_uglify(<a href="#run_uglify.ctx">ctx</a>, <a href="#run_uglify.input">input</a>, <a href="#run_uglify.output">output</a>, <a href="#run_uglify.debug">debug</a>, <a href="#run_uglify.comments">comments</a>, <a href="#run_uglify.config_name">config_name</a>, <a href="#run_uglify.in_source_map">in_source_map</a>)</pre> |
| |
| <p>Runs uglify on an input file.</p> |
| <p>This is also used by <a href="https://github.com/angular/angular">https://github.com/angular/angular</a>.</p> |
| <p>Returns: |
| The sourcemap file</p> |
| |
| |
| <h3 id="run_uglify_args">Attributes</h3> |
| |
| <table class="params-table"> |
| <colgroup> |
| <col class="col-param" /> |
| <col class="col-description" /> |
| </colgroup> |
| <tbody> |
| <tr id="run_uglify.ctx"> |
| <td><code>ctx</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>Bazel rule execution context</p> |
| </td> |
| </tr> |
| <tr id="run_uglify.input"> |
| <td><code>input</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>input file</p> |
| </td> |
| </tr> |
| <tr id="run_uglify.output"> |
| <td><code>output</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>output file</p> |
| </td> |
| </tr> |
| <tr id="run_uglify.debug"> |
| <td><code>debug</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is False</code></p> |
| <p>if True then output is beautified (defaults to False)</p> |
| </td> |
| </tr> |
| <tr id="run_uglify.comments"> |
| <td><code>comments</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is True</code></p> |
| <p>if True then copyright comments are preserved in output file (defaults to True)</p> |
| </td> |
| </tr> |
| <tr id="run_uglify.config_name"> |
| <td><code>config_name</code></td> |
| <td> |
| <p><code>Unknown; Optional</code></p> |
| <p>allows callers to control the name of the generated uglify configuration, |
| which will be <code>_[config_name].uglify.json</code> in the package where the target is declared</p> |
| </td> |
| </tr> |
| <tr id="run_uglify.in_source_map"> |
| <td><code>in_source_map</code></td> |
| <td> |
| <p><code>Unknown; Optional</code></p> |
| <p>sourcemap file for the input file, passed to the "--source-map content=" |
| option of rollup.</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <hr> |
| |
| <h2 id="run_sourcemapexplorer">run_sourcemapexplorer</h2> |
| |
| <pre>run_sourcemapexplorer(<a href="#run_sourcemapexplorer.ctx">ctx</a>, <a href="#run_sourcemapexplorer.js">js</a>, <a href="#run_sourcemapexplorer.map">map</a>, <a href="#run_sourcemapexplorer.output">output</a>)</pre> |
| |
| <p>Runs source-map-explorer to produce an HTML visualization of the sourcemap.</p> |
| |
| |
| <h3 id="run_sourcemapexplorer_args">Attributes</h3> |
| |
| <table class="params-table"> |
| <colgroup> |
| <col class="col-param" /> |
| <col class="col-description" /> |
| </colgroup> |
| <tbody> |
| <tr id="run_sourcemapexplorer.ctx"> |
| <td><code>ctx</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>bazel rule execution context</p> |
| </td> |
| </tr> |
| <tr id="run_sourcemapexplorer.js"> |
| <td><code>js</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>Javascript bundle</p> |
| </td> |
| </tr> |
| <tr id="run_sourcemapexplorer.map"> |
| <td><code>map</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>sourcemap from the bundle back to original sources</p> |
| </td> |
| </tr> |
| <tr id="run_sourcemapexplorer.output"> |
| <td><code>output</code></td> |
| <td> |
| <p><code>Unknown; Required</code></p> |
| <p>file where the HTML report is written</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <hr> |
| |
| <h2 id="rollup_bundle">rollup_bundle</h2> |
| |
| <pre>rollup_bundle(<a href="#rollup_bundle.name">name</a>, <a href="#rollup_bundle.deps">deps</a>, <a href="#rollup_bundle.srcs">srcs</a>, <a href="#rollup_bundle.additional_entry_points">additional_entry_points</a>, <a href="#rollup_bundle.entry_point">entry_point</a>, <a href="#rollup_bundle.global_name">global_name</a>, <a href="#rollup_bundle.globals">globals</a>, <a href="#rollup_bundle.license_banner">license_banner</a>, <a href="#rollup_bundle.node_modules">node_modules</a>)</pre> |
| |
| <p>Produces several bundled JavaScript files using Rollup and Uglify.</p> |
| <p>Load it with |
| <code>load("@build_bazel_rules_nodejs//:defs.bzl", "rollup_bundle")</code></p> |
| <p>It performs this work in several separate processes:</p> |
| <ol> |
| <li>Call rollup on the original sources</li> |
| <li>Downlevel the resulting code to es5 syntax for older browsers</li> |
| <li>Minify the bundle with Uglify, possibly with pretty output for human debugging.</li> |
| </ol> |
| <p>The default output of a <code>rollup_bundle</code> rule is the non-debug-minified es5 bundle.</p> |
| <p>However you can request one of the other outputs with a dot-suffix on the target's name. |
| For example, if your <code>rollup_bundle</code> is named <code>my_rollup_bundle</code>, you can use one of these labels:</p> |
| <p>To request the ES2015 syntax (e.g. <code>class</code> keyword) without downleveling or minification, use the <code>:my_rollup_bundle.es6.js</code> label. |
| To request the ES5 downleveled bundle without minification, use the <code>:my_rollup_bundle.js</code> label |
| To request the debug-minified es5 bundle, use the <code>:my_rollup_bundle.min_debug.js</code> label. |
| To request a UMD-bundle, use the <code>:my_rollup_bundle.umd.js</code> label. |
| To request a CommonJS bundle, use the <code>:my_rollup_bundle.cjs.js</code> label.</p> |
| <p>You can also request an analysis from source-map-explorer by buildng the <code>:my_rollup_bundle.explore.html</code> label. |
| However this is currently broken for <code>rollup_bundle</code> ES5 mode because we use tsc for downleveling and |
| it doesn't compose the resulting sourcemaps with an input sourcemap. |
| See <a href="https://github.com/bazelbuild/rules_nodejs/issues/175">https://github.com/bazelbuild/rules_nodejs/issues/175</a></p> |
| <p>For debugging, note that the <code>rollup.config.js</code> and <code>uglify.config.json</code> files can be found in the bazel-bin folder next to the resulting bundle.</p> |
| <p>An example usage can be found in <a href="https://github.com/bazelbuild/rules_nodejs/tree/master/internal/e2e/rollup">https://github.com/bazelbuild/rules_nodejs/tree/master/internal/e2e/rollup</a></p> |
| |
| |
| <h3 id="rollup_bundle_args">Attributes</h3> |
| |
| <table class="params-table"> |
| <colgroup> |
| <col class="col-param" /> |
| <col class="col-description" /> |
| </colgroup> |
| <tbody> |
| <tr id="rollup_bundle.name"> |
| <td><code>name</code></td> |
| <td> |
| <p><code><a href="https://bazel.build/docs/build-ref.html#name">Name</a>; Required</code></p> |
| <p>A unique name for this rule.</p> |
| </td> |
| </tr> |
| <tr id="rollup_bundle.deps"> |
| <td><code>deps</code></td> |
| <td> |
| <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> |
| <p>Other rules that produce JavaScript outputs, such as <code>ts_library</code>.</p> |
| </td> |
| </tr> |
| <tr id="rollup_bundle.srcs"> |
| <td><code>srcs</code></td> |
| <td> |
| <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> |
| <p>JavaScript source files from the workspace. |
| These can use ES2015 syntax and ES Modules (import/export)</p> |
| </td> |
| </tr> |
| <tr id="rollup_bundle.additional_entry_points"> |
| <td><code>additional_entry_points</code></td> |
| <td> |
| <p><code>List of strings; Optional; Default is []</code></p> |
| <p>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.</p> |
| <pre><code> 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 |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="rollup_bundle.entry_point"> |
| <td><code>entry_point</code></td> |
| <td> |
| <p><code>String; Required</code></p> |
| <p>The starting point of the application, passed as the <code>--input</code> flag to rollup. |
| This should be a path relative to the workspace root.</p> |
| </td> |
| </tr> |
| <tr id="rollup_bundle.global_name"> |
| <td><code>global_name</code></td> |
| <td> |
| <p><code>String; Optional; Default is ''</code></p> |
| <p>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. <code>window</code>) as a side- |
| effect of loading the UMD/IIFE JS bundle.</p> |
| <pre><code> 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. |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="rollup_bundle.globals"> |
| <td><code>globals</code></td> |
| <td> |
| <p><code>Dictionary mapping strings to string; Optional; Default is {}</code></p> |
| <p>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 |
| <code>"@angular/core":"ng.core"</code> in the globals.</p> |
| </td> |
| </tr> |
| <tr id="rollup_bundle.license_banner"> |
| <td><code>license_banner</code></td> |
| <td> |
| <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional</code></p> |
| <p>A .txt file passed to the <code>banner</code> 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 <code>0.0.0-PLACEHOLDER</code>. See the section on stamping in the README.</p> |
| </td> |
| </tr> |
| <tr id="rollup_bundle.node_modules"> |
| <td><code>node_modules</code></td> |
| <td> |
| <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is //:node_modules_none</code></p> |
| <p>Dependencies from npm that provide some modules that must be |
| resolved by rollup.</p> |
| <pre><code> 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", |
| ) |
| </code></pre> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| |
| |
| </div> |
| |
| <footer class="mdl-mini-footer"> |
| <div class="mdl-mini-footer__left-section"> |
| <div class="mdl-logo">Bazel</div> |
| <ul class="mdl-mini-footer__link-list"> |
| <li><a href="https://bazel.build">Home</a></li> |
| <li><a href="https://github.com/bazelbuild">GitHub</a></li> |
| </ul> |
| </div> |
| </footer> |
| </main> |
| </div> |
| </body> |
| </html> |
