| <!DOCTYPE html> |
| <html itemscope itemtype="https://schema.org/WebPage" lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta content="IE=edge" http-equiv="X-UA-Compatible"> |
| <meta content="width=device-width, initial-scale=1" name="viewport"> |
| <link href="/rules_nodejs/Concatjs.html" rel="canonical"> |
| <link href="" rel="shortcut icon" type="image/png"> |
| |
| <title>rules_nodejs - Concatjs</title> |
| |
| <!-- Webfont --> |
| <link href="//fonts.googleapis.com/css?family=Source+Code+Pro:400,500,700|Open+Sans:400,600,700,800" rel="stylesheet"> |
| |
| <!-- Bootstrap --> |
| <link crossorigin="anonymous" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" |
| integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" rel="stylesheet"> |
| |
| <!-- Font Awesome --> |
| <link href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet"> |
| |
| <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries --> |
| <!-- WARNING: Respond.js doesn't work if you view the page via file:// --> |
| <!--[if lt IE 9]> |
| <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script> |
| <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script> |
| <![endif]--> |
| |
| <!-- Custom stylesheet --> |
| <link href="/rules_nodejs/css/main.css" rel="stylesheet"> |
| |
| <!-- metadata --> |
| <meta content="rules_nodejs" name="og:title"/> |
| <meta content="JavaScript and NodeJS rules for Bazel" name="og:description"/> |
| </head> |
| |
| <body> |
| <nav class="navbar navbar-inverse navbar-fixed-top" id="common-nav"> |
| <div class="container"> |
| <!-- Brand and toggle get grouped for better mobile display --> |
| <div class="navbar-header"> |
| <button class="navbar-toggle collapsed" data-target="#bs-example-navbar-collapse-1" data-toggle="collapse" |
| type="button"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="navbar-brand" href="/rules_nodejs/"> |
| <img class="navbar-logo" src="/rules_nodejs/images/bazel-navbar.svg"> |
| </a> |
| </div> |
| |
| <!-- Collect the nav links, forms, and other content for toggling --> |
| <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1"> |
| <form class="navbar-form navbar-right" action="/rules_nodejs/search.html" id="cse-search-box"> |
| <div class="form-group"> |
| <input type="hidden" name="cx" value="2735dc72dd157bd19"> |
| <input type="search" name="q" id="q" class="form-control input-sm" placeholder="Search"> |
| </div> |
| </form> |
| <ul class="nav navbar-nav navbar-right"> |
| <li><a href="https://github.com/bazelbuild/rules_nodejs">GitHub</a></li> |
| </ul> |
| </div><!-- /.navbar-collapse --> |
| </div><!-- /.container-fluid --> |
| </nav> |
| |
| |
| <div class="container vpad"> |
| <div class="row"> |
| <div class="col-md-2"> |
| <a aria-controls="sidebar-nav" |
| aria-expanded="false" class="btn btn-default btn-lg btn-block sidebar-toggle" data-toggle="collapse" |
| href="#sidebar-nav"> |
| <i class="glyphicon glyphicon-menu-hamburger"></i> Navigation |
| </a> |
| |
| <nav class="sidebar collapse" id="sidebar-nav"> |
| <h3>rules_nodejs</h3> |
| <ul class="sidebar-nav"> |
| <li><a href="/rules_nodejs/">Introduction</a></li> |
| <li><a href="install.html">Installation</a></li> |
| <li><a href="repositories.html">Repositories</a></li> |
| <li><a href="dependencies.html">Dependencies</a></li> |
| <li><a href="debugging.html">Debugging</a></li> |
| <li><a href="stamping.html">Stamping</a></li> |
| <li><a href="changing-rules.html">Making changes to rules_nodejs</a></li> |
| <li><a href="examples.html">Examples</a></li> |
| </ul> |
| |
| <h3>Rules</h3> |
| <ul class="sidebar-nav"> |
| |
| |
| <li><a href="/rules_nodejs/Built-ins.html">Built-ins</a></li> |
| |
| |
| |
| <li><a href="/rules_nodejs/Concatjs.html">Concatjs</a></li> |
| |
| |
| |
| <li><a href="/rules_nodejs/Cypress.html">Cypress</a></li> |
| |
| |
| |
| <li><a href="/rules_nodejs/Jasmine.html">Jasmine</a></li> |
| |
| |
| |
| <li><a href="/rules_nodejs/Karma.html">Karma</a></li> |
| |
| |
| |
| <li><a href="/rules_nodejs/Labs.html">Labs</a></li> |
| |
| |
| |
| <li><a href="/rules_nodejs/Protractor.html">Protractor</a></li> |
| |
| |
| |
| <li><a href="/rules_nodejs/Rollup.html">Rollup</a></li> |
| |
| |
| |
| <li><a href="/rules_nodejs/Terser.html">Terser</a></li> |
| |
| |
| |
| <li><a href="/rules_nodejs/TypeScript.html">TypeScript</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| <h3>Community</h3> |
| <ul class="sidebar-nav"> |
| <li><a href="https://github.com/bazelbuild/rules_nodejs/blob/master/CONTRIBUTING.md">Contribute to |
| rules_nodejs</a></li> |
| <li><a href="https://slack.bazel.build">Join #javascript on Slack</a></li> |
| <li><a href="https://github.com/bazelbuild/rules_nodejs/issues">Issue Tracker</a></li> |
| <li><a href="https://github.com/bazelbuild/rules_nodejs">Github</a></li> |
| </ul> |
| </nav> |
| </div> |
| |
| |
| <div class="col-md-8"> |
| <div class="content"> |
| <!-- ********************* |
| DO NOT EDIT THIS FILE |
| It is a generated build output from Stardoc. |
| Instead you must edit the .bzl file where the rules are declared, |
| or possibly a markdown file next to the .bzl file |
| ********************* --> |
| <h1 id="bazelconcatjs">@bazel/concatjs</h1> |
| |
| <p>Concatjs is a JavaScript bundler, in a trivial sense: the UNIX <code class="language-plaintext highlighter-rouge">cat</code> command is a basic implementation:</p> |
| |
| <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">cat </span>one.js two.js <span class="o">></span> bundle.js |
| </code></pre></div></div> |
| |
| <p>Clearly self-evident is that this bundler is super-fast and simple. |
| A performant implementation adds some in-memory caching, and for developer ergonomics you add a simple IIFE wrapper |
| around each file so that the Chrome DevTools shows the files in the tree as if they had been independently loaded.</p> |
| |
| <p>However at its core, concatjs requires a big tradeoff of a migration cost to buy-in, to get this incredible performance. |
| The path of the JavaScript files is lost in the bundling process, so they must contain their module ID internally.</p> |
| |
| <p>Named AMD/UMD (non-anonymous require.js modules) and <code class="language-plaintext highlighter-rouge">goog.module</code> are the two JS module formats that are compatible with concatjs. |
| Most packages do not ship with this format, so in order to use concatjs tooling, you have to shim your code and dependencies.</p> |
| |
| <p>This is at the core of how Google does JavaScript development. |
| So Bazel rules that originated in Google’s codebase, such as <code class="language-plaintext highlighter-rouge">ts_library</code> depend in some ways on producing concatjs output.</p> |
| |
| <h2 id="serving-js-in-development-mode-under-bazel">Serving JS in development mode under Bazel</h2> |
| |
| <p>There are two choices for development mode:</p> |
| |
| <ol> |
| <li>Use the <code class="language-plaintext highlighter-rouge">concatjs_devserver</code> rule to bring up our simple, fast development server. |
| This is intentionally very simple, to help you get started quickly. However, |
| since there are many development servers available, we do not want to mirror |
| their features in yet another server we maintain.</li> |
| <li>Teach your real frontend server to serve files from Bazel’s output directory. |
| This is not yet documented. Choose this option if you have an existing server |
| used in development mode, or if your requirements exceed what the |
| <code class="language-plaintext highlighter-rouge">concatjs_devserver</code> supports. Be careful that your development round-trip stays |
| fast (should be under two seconds).</li> |
| </ol> |
| |
| <p>To use <code class="language-plaintext highlighter-rouge">concatjs_devserver</code>, you simply <code class="language-plaintext highlighter-rouge">load</code> the rule, and call it with <code class="language-plaintext highlighter-rouge">deps</code> that |
| point to your <code class="language-plaintext highlighter-rouge">ts_library</code> target(s):</p> |
| |
| <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">load</span><span class="p">(</span><span class="s">"@npm//@bazel/typescript:index.bzl"</span><span class="p">,</span> <span class="s">"concatjs_devserver"</span><span class="p">,</span> <span class="s">"ts_library"</span><span class="p">)</span> |
| |
| <span class="n">ts_library</span><span class="p">(</span> |
| <span class="n">name</span> <span class="o">=</span> <span class="s">"app"</span><span class="p">,</span> |
| <span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"app.ts"</span><span class="p">],</span> |
| <span class="p">)</span> |
| |
| <span class="n">concatjs_devserver</span><span class="p">(</span> |
| <span class="n">name</span> <span class="o">=</span> <span class="s">"devserver"</span><span class="p">,</span> |
| <span class="c1"># We'll collect all the devmode JS sources from these TypeScript libraries |
| </span> <span class="n">deps</span> <span class="o">=</span> <span class="p">[</span><span class="s">":app"</span><span class="p">],</span> |
| <span class="c1"># This is the path we'll request from the browser, see index.html |
| </span> <span class="n">serving_path</span> <span class="o">=</span> <span class="s">"/bundle.js"</span><span class="p">,</span> |
| <span class="c1"># The devserver can serve our static files too |
| </span> <span class="n">static_files</span> <span class="o">=</span> <span class="p">[</span><span class="s">"index.html"</span><span class="p">],</span> |
| <span class="p">)</span> |
| </code></pre></div></div> |
| |
| <p>The <code class="language-plaintext highlighter-rouge">index.html</code> should be the same one you use for production, and it should |
| load the JavaScript bundle from the path indicated in <code class="language-plaintext highlighter-rouge">serving_path</code>.</p> |
| |
| <p>If you don’t have an index.html file, a simple one will be generated by the |
| <code class="language-plaintext highlighter-rouge">concatjs_devserver</code>.</p> |
| |
| <p>See <code class="language-plaintext highlighter-rouge">examples/app</code> in this repository for a working example. To run the |
| devserver, we recommend you use <a href="https://github.com/bazelbuild/bazel-watcher">ibazel</a>:</p> |
| |
| <div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>ibazel run examples/app:devserver |
| </code></pre></div></div> |
| |
| <p><code class="language-plaintext highlighter-rouge">ibazel</code> will keep the devserver program running, and provides a LiveReload |
| server so the browser refreshes the application automatically when each build |
| finishes.</p> |
| |
| <h2 id="concatjs_devserver">concatjs_devserver</h2> |
| |
| <p><strong>USAGE</strong></p> |
| |
| <pre> |
| concatjs_devserver(<a href="#concatjs_devserver-name">name</a>, <a href="#concatjs_devserver-additional_root_paths">additional_root_paths</a>, <a href="#concatjs_devserver-bootstrap">bootstrap</a>, <a href="#concatjs_devserver-deps">deps</a>, <a href="#concatjs_devserver-devserver">devserver</a>, <a href="#concatjs_devserver-devserver_host">devserver_host</a>, |
| <a href="#concatjs_devserver-entry_module">entry_module</a>, <a href="#concatjs_devserver-port">port</a>, <a href="#concatjs_devserver-scripts">scripts</a>, <a href="#concatjs_devserver-serving_path">serving_path</a>, <a href="#concatjs_devserver-static_files">static_files</a>) |
| </pre> |
| |
| <p>concatjs_devserver is a simple development server intended for a quick “getting started” experience.</p> |
| |
| <p>Additional documentation at https://github.com/alexeagle/angular-bazel-example/wiki/Running-a-devserver-under-Bazel</p> |
| |
| <p><strong>ATTRIBUTES</strong></p> |
| |
| <h4 id="concatjs_devserver-name">name</h4> |
| |
| <p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory</em>): A unique name for this target.</p> |
| |
| <h4 id="concatjs_devserver-additional_root_paths">additional_root_paths</h4> |
| |
| <p>(<em>List of strings</em>): Additional root paths to serve <code class="language-plaintext highlighter-rouge">static_files</code> from. |
| Paths should include the workspace name such as <code class="language-plaintext highlighter-rouge">["__main__/resources"]</code></p> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p> |
| |
| <h4 id="concatjs_devserver-bootstrap">bootstrap</h4> |
| |
| <p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Scripts to include in the JS bundle before the module loader (require.js)</p> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p> |
| |
| <h4 id="concatjs_devserver-deps">deps</h4> |
| |
| <p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Targets that produce JavaScript, such as <code class="language-plaintext highlighter-rouge">ts_library</code></p> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p> |
| |
| <h4 id="concatjs_devserver-devserver">devserver</h4> |
| |
| <p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a></em>): Go based devserver executable.</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> With cross-platform RBE for OSX & Windows ctx.executable.devserver will be linux as --cpu and |
| --host_cpu must be overridden to k8. However, we still want to be able to run the devserver on the host |
| machine so we need to include the host devserver binary, which is ctx.executable.devserver_host, in the |
| runfiles. For non-RBE and for RBE with a linux host, ctx.executable.devserver & ctx.executable.devserver_host |
| will be the same binary. |
| |
| Defaults to precompiled go binary setup by @bazel/typescript npm package |
| </code></pre></div></div> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">@npm//@bazel/devserver:devserver</code></p> |
| |
| <h4 id="concatjs_devserver-devserver_host">devserver_host</h4> |
| |
| <p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a></em>): Go based devserver executable for the host platform. |
| Defaults to precompiled go binary setup by @bazel/typescript npm package</p> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">@npm//@bazel/devserver:devserver_darwin_amd64</code></p> |
| |
| <h4 id="concatjs_devserver-entry_module">entry_module</h4> |
| |
| <p>(<em>String</em>): The <code class="language-plaintext highlighter-rouge">entry_module</code> should be the AMD module name of the entry module such as <code class="language-plaintext highlighter-rouge">"__main__/src/index".</code> |
| <code class="language-plaintext highlighter-rouge">concatjs_devserver</code> concats the following snippet after the bundle to load the application: |
| <code class="language-plaintext highlighter-rouge">require(["entry_module"]);</code></p> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p> |
| |
| <h4 id="concatjs_devserver-port">port</h4> |
| |
| <p>(<em>Integer</em>): The port that the devserver will listen on.</p> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">5432</code></p> |
| |
| <h4 id="concatjs_devserver-scripts">scripts</h4> |
| |
| <p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): User scripts to include in the JS bundle before the application sources</p> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p> |
| |
| <h4 id="concatjs_devserver-serving_path">serving_path</h4> |
| |
| <p>(<em>String</em>): The path you can request from the client HTML which serves the JavaScript bundle. |
| If you don’t specify one, the JavaScript can be loaded at /_/ts_scripts.js</p> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">"/_/ts_scripts.js"</code></p> |
| |
| <h4 id="concatjs_devserver-static_files">static_files</h4> |
| |
| <p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Arbitrary files which to be served, such as index.html. |
| They are served relative to the package where this rule is declared.</p> |
| |
| <p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p> |
| |
| |
| </div> |
| </div> |
| |
| <div class="col-md-2 sticky-sidebar"> |
| <div class="right-sidebar"> |
| <ul class="gh-links"> |
| <li> |
| <i class="fa fa-github"></i> |
| <a href="https://github.com/bazelbuild/rules_nodejs/issues/new?title=Documentation issue: Concatjs&labels=question/docs">Create |
| issue</a> |
| </li> |
| |
| </ul> |
| <ul class="section-nav"> |
| <li class="toc-entry toc-h2"><a href="#serving-js-in-development-mode-under-bazel">Serving JS in development mode under Bazel</a></li> |
| <li class="toc-entry toc-h2"><a href="#concatjs_devserver">concatjs_devserver</a></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <footer class="footer"> |
| <div class="container"> |
| <div class="row"> |
| <div class="col-lg-8"> |
| <p class="text-muted">© 2020 The rules_nodejs authors</p> |
| </div> |
| </div> |
| </div> |
| |
| </footer> |
| |
| <!-- jQuery (necessary for Bootstrap's JavaScript plugins) --> |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script> |
| <!-- Include all compiled plugins (below), or include individual files as needed --> |
| <script crossorigin="anonymous" |
| integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" |
| src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script> |
| |
| <!-- Anchor JS --> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/3.2.0/anchor.min.js" type="text/javascript"></script> |
| <script> |
| // Automatically add anchors and links to all header elements that don't already have them. |
| anchors.options = { placement: 'left' }; |
| anchors.add(); |
| </script> |
| |
| <script> |
| var shiftWindow = function () { |
| if (location.hash.length !== 0) { |
| window.scrollBy(0, -50); |
| } |
| }; |
| window.addEventListener("hashchange", shiftWindow); |
| |
| var highlightCurrentSidebarNav = function () { |
| var href = location.pathname; |
| var item = $('#sidebar-nav [href$="' + href + '"]'); |
| if (item) { |
| var li = item.parent(); |
| li.addClass("active"); |
| |
| if (li.parent() && li.parent().is("ul")) { |
| do { |
| var ul = li.parent(); |
| if (ul.hasClass("collapse")) { |
| ul.collapse("show"); |
| } |
| li = ul.parent(); |
| } while (li && li.is("li")); |
| } |
| } |
| }; |
| |
| $(document).ready(function () { |
| // Scroll to anchor of location hash, adjusted for fixed navbar. |
| window.setTimeout(function () { |
| shiftWindow(); |
| }, 1); |
| |
| // Flip the caret when submenu toggles are clicked. |
| $(".sidebar-submenu").on("show.bs.collapse", function () { |
| var toggle = $('[href$="#' + $(this).attr('id') + '"]'); |
| if (toggle) { |
| toggle.addClass("dropup"); |
| } |
| }); |
| $(".sidebar-submenu").on("hide.bs.collapse", function () { |
| var toggle = $('[href$="#' + $(this).attr('id') + '"]'); |
| if (toggle) { |
| toggle.removeClass("dropup"); |
| } |
| }); |
| |
| // Highlight the current page on the sidebar nav. |
| highlightCurrentSidebarNav(); |
| }); |
| </script> |
| |
| </body> |
| </html> |
| |
