docs/Concatjs.md

---
title: Concatjs
layout: default
toc: true
nav: rule
---
<!-- *********************
  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
 ********************* -->
# @bazel/concatjs

Concatjs is a JavaScript bundler, in a trivial sense: the UNIX `cat` command is a basic implementation:

```bash
$ 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.

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.

Named AMD/UMD (non-anonymous require.js 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.

This is at the core of how Google does JavaScript development.
So Bazel rules that originated in Google's codebase, such as `ts_library` depend in some ways on producing concatjs output.


## Serving JS in development mode under Bazel

There are two choices for development mode:

1. Use the `concatjs_devserver` 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.
1. 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_devserver` supports. Be careful that your development round-trip stays
   fast (should be under two seconds).

To use `concatjs_devserver`, you simply `load` the rule, and call it with `deps` that
point to your `ts_library` target(s):

```python
load("@npm//@bazel/typescript:index.bzl", "concatjs_devserver", "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"],
)
```

The `index.html` should be the same one you use for production, and it should
load the JavaScript bundle from the path indicated in `serving_path`.

If you don't have an index.html file, a simple one will be generated by the
`concatjs_devserver`.

See `examples/app` in this repository for a working example. To run the
devserver, we recommend you use [ibazel]:

```sh
$ 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
finishes.

[ibazel]: https://github.com/bazelbuild/bazel-watcher


## concatjs_devserver

**USAGE**

<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>

concatjs_devserver is a simple development server intended for a quick "getting started" experience.

Additional documentation at https://github.com/alexeagle/angular-bazel-example/wiki/Running-a-devserver-under-Bazel


**ATTRIBUTES**


<h4 id="concatjs_devserver-name">name</h4>

(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.


<h4 id="concatjs_devserver-additional_root_paths">additional_root_paths</h4>

(*List of strings*): Additional root paths to serve `static_files` from.
            Paths should include the workspace name such as `["__main__/resources"]`

Defaults to `[]`

<h4 id="concatjs_devserver-bootstrap">bootstrap</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Scripts to include in the JS bundle before the module loader (require.js)

Defaults to `[]`

<h4 id="concatjs_devserver-deps">deps</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Targets that produce JavaScript, such as `ts_library`

Defaults to `[]`

<h4 id="concatjs_devserver-devserver">devserver</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): 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

Defaults to `@npm//@bazel/devserver:devserver`

<h4 id="concatjs_devserver-devserver_host">devserver_host</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): Go based devserver executable for the host platform.
            Defaults to precompiled go binary setup by @bazel/typescript npm package

Defaults to `@npm//@bazel/devserver:devserver_darwin_amd64`

<h4 id="concatjs_devserver-entry_module">entry_module</h4>

(*String*): The `entry_module` should be the AMD module name of the entry module such as `"__main__/src/index".`
            `concatjs_devserver` concats the following snippet after the bundle to load the application:
            `require(["entry_module"]);`

Defaults to `""`

<h4 id="concatjs_devserver-port">port</h4>

(*Integer*): The port that the devserver will listen on.

Defaults to `5432`

<h4 id="concatjs_devserver-scripts">scripts</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): User scripts to include in the JS bundle before the application sources

Defaults to `[]`

<h4 id="concatjs_devserver-serving_path">serving_path</h4>

(*String*): 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

Defaults to `"/_/ts_scripts.js"`

<h4 id="concatjs_devserver-static_files">static_files</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Arbitrary files which to be served, such as index.html.
            They are served relative to the package where this rule is declared.

Defaults to `[]`