| |
| |
| <!-- |
| 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/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>)</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> |
| </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.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.</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.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</code></p> |
| <p>Dependencies from npm that provide some modules that must be resolved by rollup.</p> |
| </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> |
