cat command is a basic implementation:
$ cat one.js two.js > bundle.js
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.
Named AMD/UMD modules and
goog.module 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. See the Compatibility section below.
So Bazel rules that originated in Google’s codebase have affordances for concatjs.
ts_library produces named AMD modules in its “devmode” output, and
karma_web_test expects to bundle inputs using concatjs.
To make it easier to produce a UMD version of a third-party npm package, we automatically generate a target that uses Browserify to build one, using the
main entry from the package’s
In most cases this will make the package loadable under concatjs.
This target has a
__umd suffix. For example, if your library is at
@npm//foo then the UMD target is
An example where this fixes a users issue: https://github.com/bazelbuild/rules_nodejs/issues/2317#issuecomment-735921318
In some cases, the generated UMD bundle is not sufficient, and in others it fails to build because it requires some special Browserify configuration.
You can always write your own shim that grabs a symbol from a package you use, and exposes it in an AMD/require.js-compatible way.
For example, even though RxJS ships with a UMD bundle, it contains multiple entry points and uses anonymous modules, not named modules. So our Angular/concatjs example has a
rxjs_shims.js file that exposes some RxJS operators, then at https://github.com/bazelbuild/rules_nodejs/blob/2.3.1/examples/angular/src/BUILD.bazel#L65-L71 this is combined in a
filegroup with the
rxjs.umd.js file. Now we use this filegroup target when depending on RxJS in a
Ultimately by using concatjs, you’re signing up for at least a superficial understanding of these shims and may need to update them when you change your dependencies.
Serving JS in development mode under Bazel
There are two choices for development mode:
- Use the
concatjs_devserverrule 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.
- 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
concatjs_devserversupports. Be careful that your development round-trip stays fast (should be under two seconds).
concatjs_devserver, you simply
load the rule, and call it with
point to your
load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver") load("@npm//@bazel/typescript:index.bzl", "ts_library") ts_library( name = "app", srcs = ["app.ts"], ) concatjs_devserver( name = "devserver", # We'll collect all the devmode JS sources from these TypeScript libraries deps = [":app"], # This is the path we'll request from the browser, see index.html serving_path = "/bundle.js", # The devserver can serve our static files too static_files = ["index.html"], )
index.html should be the same one you use for production, and it should
If you don’t have an index.html file, a simple one will be generated by the
examples/app in this repository for a working example. To run the
devserver, we recommend you use ibazel:
$ ibazel run examples/app:devserver
ibazel will keep the devserver program running, and provides a LiveReload
server so the browser refreshes the application automatically when each build
Testing with Karma
karma_web_test rule runs karma tests with Bazel.
It depends on rules_webtesting, so you need to add this to your
if you use the web testing rules in
# Fetch transitive Bazel dependencies of karma_web_test http_archive( name = "io_bazel_rules_webtesting", sha256 = "9bb461d5ef08e850025480bab185fd269242d4e533bca75bfb748001ceb343c3", urls = ["https://github.com/bazelbuild/rules_webtesting/releases/download/0.3.3/rules_webtesting.tar.gz"], ) # Set up web testing, choose browsers we can test on load("@io_bazel_rules_webtesting//web:repositories.bzl", "web_test_repositories") web_test_repositories() load("@io_bazel_rules_webtesting//web/versioned:browsers-0.3.2.bzl", "browser_repositories") browser_repositories( chromium = True, firefox = True, )
Installing with user-managed dependencies
If you didn’t use the
npm_install rule to create an
npm workspace, you’ll have to declare a rule in your root
BUILD.bazel file to execute karma:
# Create a karma rule to use in karma_web_test_suite karma # attribute when using user-managed dependencies nodejs_binary( name = "karma/karma", entry_point = "//:node_modules/karma/bin/karma", # Point bazel to your node_modules to find the entry point data = ["//:node_modules"], )
concatjs_devserver(name, additional_root_paths, bootstrap, deps, devserver, devserver_host, entry_module, port, scripts, serving_path, static_files)
concatjs_devserver is a simple development server intended for a quick “getting started” experience.
Additional documentation here
(Name, mandatory): A unique name for this target.
(List of strings): Additional root paths to serve
Paths should include the workspace name such as
(List of labels): Scripts to include in the JS bundle before the module loader (require.js)
(Label): Go based devserver executable.
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
(Label): Go based devserver executable for the host platform. Defaults to precompiled go binary setup by @bazel/typescript npm package
entry_module should be the AMD module name of the entry module such as
concatjs_devserver concats the following snippet after the bundle to load the application:
(Integer): The port that the devserver will listen on.
(List of labels): User scripts to include in the JS bundle before the application sources
(List of labels): Arbitrary files which to be served, such as index.html. They are served relative to the package where this rule is declared.
karma_web_test(srcs, deps, data, configuration_env_vars, bootstrap, runtime_deps, static_files, config_file, tags, peer_deps, kwargs)
Runs unit tests in a browser with Karma.
When executed under
bazel test, this uses a headless browser for speed.
This is also because
bazel test allows multiple targets to be tested together,
and we don’t want to open a Chrome window on your machine for each one. Also,
bazel test the test will execute and immediately terminate.
ibazel test gives you a “watch mode” for your tests. The rule is
optimized for this case - the test runner server will stay running and just
To debug a single test target, run it with
bazel run instead. This will open a
browser window on your computer. Also you can use any other browser by opening
the URL printed when the test starts up. The test will remain running until you
bazel run command.
This rule will use your system Chrome by default. In the default case, your
environment must specify CHROME_BIN so that the rule will know which Chrome binary to run.
customLaunchers may be set using the a base Karma configuration
specified in the
By default we open a headless Chrome. To use a real Chrome browser window, you can pass
--define DISPLAY=true to Bazel, along with
configuration_env_vars = ["DISPLAY"] on
Pass these configuration environment variables to the resulting binary. Chooses a subset of the configuration environment variables (taken from ctx.var), which also includes anything specified via the –define flag. Note, this can lead to different outputs produced by this rule.
Dependencies which should be loaded after the module loader but before the srcs and deps.
The files will be loaded in the same order they are declared by that rule.
Arbitrary files which are available to be served on request.
Files are served at:
User supplied Karma configuration file. Bazel will override certain attributes of this configuration file. Attributes that are overridden will be outputted to the test log.
Standard Bazel tags, this macro adds tags for ibazel support
list of peer npm deps required by karma_web_test
["@npm//karma", "@npm//karma-chrome-launcher", "@npm//karma-firefox-launcher", "@npm//karma-jasmine", "@npm//karma-requirejs", "@npm//karma-sourcemap-loader", "@npm//requirejs"]
Passed through to
karma_web_test_suite(name, browsers, web_test_data, wrapped_test_tags, kwargs)
Defines a test_suite of web_test targets that wrap a karma_web_test target.
This macro accepts all parameters in karma_web_test and adds additional parameters for the suite. See karma_web_test docs for all karma_web_test.
The wrapping macro is
web_test_suite which comes from rules_websting:
The base name of the test
A sequence of labels specifying the browsers to use.
Data dependencies for the wrapper web_test targets.
A list of test tag strings to use for the wrapped karma_web_test target.
Arguments for the wrapped karma_web_test target.