<!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/examples.html" rel="canonical">

<link href="" rel="shortcut icon" type="image/png">

<title>rules_nodejs - Examples</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/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">

<h1 id="examples">Examples</h1>

<h2 id="frameworks">Frameworks</h2>

<h3 id="angular">Angular</h3>

<p>Bazel can run any toolchain you want, so there is more than one way to use it with Angular.

See Alex’s post <a href="https://dev.to/bazel/angular-bazel-leaving-angular-labs-51ja">Angular ❤️ Bazel update</a> for a longer explanation.</p>

<p><strong>Architect</strong>: The first approach is the simplest: use Architect (aka. Angular CLI Builders). This is the build tool inside of Angular CLI, so your existing application will continue to work the same way, and you can still get support from the Angular team. This may be a good choice if your goal is just to include an Angular app in a full-stack Bazel build that includes your backend, and making the Angular build&amp;test faster is not important for you.</p>

<p>However, it has the worst performance because the level of incrementality is only as fine as how many libs your application is composed from.

Bazel can only make a build more parallel and incremental if you express a wider dependency graph to it.</p>

<p>Example: <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular_bazel_architect">examples/angular_bazel_architect</a></p>

<p><strong>Google</strong>: This toolchain is what we originally advertised as “Angular Buildtools Convergence” (ABC). It is based on Google’s internal toolchain for building Angular, and has good performance characteristics. However it is harder to migrate to, because it doesn’t have good compatibility for existing applications.</p>

<p>The example has its own guide: <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular">examples/angular</a></p>

<p><strong>View Engine</strong>: If you’re stuck on the older Angular compiler/runtime before Ivy, called View Engine, then your options are more limited. We don’t support Angular 9 + View Engine + Bazel.</p>

<p>Example: <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular_view_engine">examples/angular_view_engine</a></p>

<p><strong>Custom</strong>: Bazel is excellent for advanced use cases where you need to customize your toolchain.

Take any off-the-shelf tools, follow their README’s to call their CLI, and assemble them together in a custom way.

This lets you take advantage of the latest JS ecosystem innovations without waiting for tooling vendors to

assemble it all together for you.</p>

<h3 id="react">React</h3>

<p>Similar to the explanation above for Angular, Bazel is agnostic to what tools you choose to run on your project.

However, the benefits of using Bazel are unlocked as you adopt it as your build system.

We think the following examples show a typical migration of adopting Bazel:</p>

<p><strong>create-react-app</strong>: If you run <code class="language-plaintext highlighter-rouge">create-react-app</code>, it will install a build system called <code class="language-plaintext highlighter-rouge">react-scripts</code>.

As a first step into Bazel, you can simply ask Bazel to wrap the existing build system.

This guarantees compatibility with your current code, and if your objective is just to include a frontend app into

a bigger full-stack Bazel build, this might be the final step in the migration.

However it will run <code class="language-plaintext highlighter-rouge">react-scripts</code> as a single Bazel action, which means that you gain no incrementality benefit.

So we expect for most applications this is just a first step.</p>

<p>The <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/create-react-app">create-react-app example</a>

shows how this will look. We suggest reading the README in that example, and also look at the commit history to that

directory as an illustration of how we started from create-react-app and added Bazel bits.</p>

<p><strong>react-scripts-like</strong>: As a next step to make our Build more incremental and performant, we can replace the <code class="language-plaintext highlighter-rouge">react-scripts</code> build system with Bazel, but preserve compatibility as much as possible by having Bazel run

mostly the same tools with mostly identical configuration. We continue to transpile TS to JS using Babel, for example,

but we do it in a build step before invoking Webpack, just using the Babel CLI.</p>

<p>This is a good middle ground to get some benefits from Bazel while staying on the same supported tools as react-scripts.</p>

<p>TODO(alexeagle): build an example illustrating how this looks</p>

<p><strong>custom</strong>: If you really know your JS build tools, Bazel is the perfect way to assemble all the myriad individual tools

into a custom toolchain. This allows you to unlock any part of the JS ecosystem without waiting for it to be integrated

for you by maintainers of a project like create-react-app, who have a very high bar for adding features since the

maintenance and support burden falls on them. However you’ll need to understand both the tools as well as Bazel to

successfully build your own toolchain.</p>

<p>There is a basic example at <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/react_webpack">examples/react_webpack</a> but it needs a lot more work to show everything that is possible!</p>

<h3 id="vue">Vue</h3>

<p>We don’t have a dedicated example yet, but Vue has been known to work. Follow https://github.com/bazelbuild/rules_nodejs/issues/1840 for an example.</p>

<h3 id="svelte">Svelte</h3>

<p>None yet, please file an issue if you need this.</p>

<h2 id="test-runners">Test Runners</h2>

<h3 id="jest">Jest</h3>

<p>There is a dedicated example for Jest: <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/jest">examples/jest</a></p>

<h3 id="cypress">Cypress</h3>

<p>We have done some early work to run Cypress under Bazel. Follow https://github.com/bazelbuild/rules_nodejs/issues/1904 for an example.</p>

<h3 id="mocha">Mocha</h3>

<p>Example at <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/webapp">examples/webapp</a> has a simple <code class="language-plaintext highlighter-rouge">mocha_test</code></p>

<h3 id="karma-and-protractor">Karma and Protractor</h3>

<p>See Protractor usage in <a href="https://github.com/bazelbuild/rules_nodejs/blob/master/examples/app/">examples/app</a></p>

<h2 id="bundlers">Bundlers</h2>

<h3 id="webpack">Webpack</h3>

<p>See <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/react_webpack">examples/react_webpack</a></p>

<h3 id="rollup">Rollup</h3>

<p>The example at <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/webapp">examples/webapp</a> uses Rollup, and produces an app with ES5 and ES2015 variants (“differential loading”) that gives faster loading in modern browsers without dropping support for legacy ones.</p>

<h3 id="parcel">Parcel</h3>

<p>The example in <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/parcel">examples/parcel</a> shows how to write a custom rule, it happens to use the parcel binary to build. It’s a very minimal example but might be enough to get you started.</p>

<h2 id="language-tooling">Language tooling</h2>

<h3 id="less-sass-stylus">LESS, Sass, Stylus</h3>

<p>See styles directory inside the <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/app/styles">examples/app</a> example.</p>

<h3 id="typescript">TypeScript</h3>

<p>Most of the examples show TypeScript usage. Also look in <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/typescript/test">packages/typescript/test</a> for lots of handling of edge cases.</p>

<h3 id="kotlin">Kotlin</h3>

<p>The Kotlin language can compile to JS. The result has a very large stdlib JS payload, so we don’t recommend this for most uses.</p>

<p>Example at <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/kotlin">examples/kotlin</a></p>

<h3 id="google-closure-compiler">Google Closure Compiler</h3>

<p><a href="https://github.com/bazelbuild/rules_closure">rules_closure</a> is a whole-cloth approach to using Bazel if you’re fully bought-into the Closure ecosystem.</p>

<p><a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/closure">examples/closure</a> shows a very simple way to call the closure compiler without jumping into that ecosystem.</p>

<h3 id="protocol-buffers-and-grpc">Protocol Buffers and gRPC</h3>

<p>Note: this is considered a “labs” feature in rules_nodejs, so support and stability are not great. gRPC is still a WIP.</p>

<p>See <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/protocol_buffers">examples/protocol_buffers</a></p>

<h2 id="bazel-specific">Bazel-specific</h2>

<h3 id="bazel-persistent-workers">Bazel Persistent Workers</h3>

<p>If you want to speed up Bazel by keeping some tools running warm in the background as daemons, there’s a good readme in the <a href="https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/worker">examples/worker</a></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: Examples&labels=question/docs">Create

issue</a>

</li>

<li>

<i class="fa fa-pencil"></i>

<a class="gh-edit" href="https://github.com/bazelbuild/rules_nodejs/tree/stable/docs/examples.md">Edit

this page</a>

</li>

</ul>

<ul class="section-nav">

<li class="toc-entry toc-h2"><a href="#frameworks">Frameworks</a>

<ul>

<li class="toc-entry toc-h3"><a href="#angular">Angular</a></li>

<li class="toc-entry toc-h3"><a href="#react">React</a></li>

<li class="toc-entry toc-h3"><a href="#vue">Vue</a></li>

<li class="toc-entry toc-h3"><a href="#svelte">Svelte</a></li>

</ul>

</li>

<li class="toc-entry toc-h2"><a href="#test-runners">Test Runners</a>

<ul>

<li class="toc-entry toc-h3"><a href="#jest">Jest</a></li>

<li class="toc-entry toc-h3"><a href="#cypress">Cypress</a></li>

<li class="toc-entry toc-h3"><a href="#mocha">Mocha</a></li>

<li class="toc-entry toc-h3"><a href="#karma-and-protractor">Karma and Protractor</a></li>

</ul>

</li>

<li class="toc-entry toc-h2"><a href="#bundlers">Bundlers</a>

<ul>

<li class="toc-entry toc-h3"><a href="#webpack">Webpack</a></li>

<li class="toc-entry toc-h3"><a href="#rollup">Rollup</a></li>

<li class="toc-entry toc-h3"><a href="#parcel">Parcel</a></li>

</ul>

</li>

<li class="toc-entry toc-h2"><a href="#language-tooling">Language tooling</a>

<ul>

<li class="toc-entry toc-h3"><a href="#less-sass-stylus">LESS, Sass, Stylus</a></li>

<li class="toc-entry toc-h3"><a href="#typescript">TypeScript</a></li>

<li class="toc-entry toc-h3"><a href="#kotlin">Kotlin</a></li>

<li class="toc-entry toc-h3"><a href="#google-closure-compiler">Google Closure Compiler</a></li>

<li class="toc-entry toc-h3"><a href="#protocol-buffers-and-grpc">Protocol Buffers and gRPC</a></li>

</ul>

</li>

<li class="toc-entry toc-h2"><a href="#bazel-specific">Bazel-specific</a>

<ul>

<li class="toc-entry toc-h3"><a href="#bazel-persistent-workers">Bazel Persistent Workers</a></li>

</ul>

</li>

</ul>

</div>

</div>

</div>

</div>

<footer class="footer">

<div class="container">

<div class="row">

<div class="col-lg-8">

<p class="text-muted">&copy; 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>