TypeScript rules

TypeScript is a popular typed language that is a superset of the JavaScript you already know, and compiles down to plain JavaScript.

Source location: rules_typescript

Issues: https://github.com/bazelbuild/rules_typescript/issues

Setup

To set up the TypeScript rules, add them to your WORKSPACE file:

git_repository(
    name = "build_bazel_rules_typescript",
    remote = "https://github.com/bazelbuild/rules_typescript.git",
    tag = "0.7.1",
)

load("@build_bazel_rules_typescript//:setup.bzl", "ts_setup_workspace")

ts_setup_workspace(default_tsconfig = "//:tsconfig.json")

An important thing to note here is that we pick the same tsconfig.json file used by the editor as the default for our TypeScript compilations. This ensures the same options (eg. --strictNullChecks) are applied by Bazel as those shown while you code. The settings can be overridden in each library with the tsconfig attribute.

Finally, be sure you added the --strategy settings from the Getting Started to your bazel.rc file to make the TypeScript compiler run faster.

Usage

Compiling TypeScript

ts_library compiles one package of TypeScript code. Each library is compiled independently, using the .d.ts declaration files from the dependencies. That means a package is only re-built when an API it depends on is changed.

You can try the ts_library rule by running bazel build src in this example repo.

Attributes:

• srcs are some TypeScript files (.ts and .d.ts)
• deps are any rules that produce .d.ts outputs, typically other ts_library rules.
• tsconfig points to your tsconfig.json file, which is important so the editor uses the same TypeScript settings as Bazel.

Outputs:

• default: .d.ts file for each input .ts file.
• in the same output directory with the .d.ts outputs, there is an ES5 (devmode) .js file, intended for consumption by rules that depend (maybe transitively) on this one.

We recommend few tsconfig.json files, ideally just one for your whole repository, or even your whole company if it’s not too late (we do that at Google).

Note that Bazel controls parts of the tsconfig, namely those related to locating inputs and outputs, managing dependencies on typings, and producing JavaScript output that’s readable by downstream tooling. (Currently this format is un-bundled UMD modules, wrapping both named (non-anonymous) AMD modules and commonjs modules. Bazel may introduce new requirements on your TS code, for example, we always use –declarations to produce .d.ts outputs needed by dependent rules, and your code may have some errors which only manifest under that rule.

If you find this rule is running slowly, consider breaking it into multiple rules, then declare the dependencies between them (you may have to do some refactoring to find a non-cyclical partitioning of the code, otherwise Bazel errors)

Running a development server

The ts_devserver rule brings up a development server from your application sources. It's intended to be used with ibazel run, so that the devserver picks up your code changes immediately. It will inject a livereload script into the browser, so the page will automatically refresh with your changes after each build completes.

You can try the devserver by running ibazel run src:devserver in this example repo.

Attributes:

• deps are your application sources, typically ts_library or ng_module targets
• scripts are other sources which are not dependencies of your deps, but which should be included in the bundled JavaScript
• serving_path is what URL the server exposes for the bundled JavaScript. This is optional; if not specified the bundle is served at /_/ts_scripts.js
• static_files are other files, such as images or HTML, which should be served. Note that the devserver only serves files from the package where the ts_devserver rule is declared.
• entry_module is the AMD module name of the application entry point. It should start with your workspace name, eg. my_workspace/path/to/main for an input path/to/main.js

Notes:

• In development mode, the ts_library rule produces JavaScript in a UMD format, with named AMD modules inside. This allows us to bundle them with a simple cat command, which is fast and simple.
• The ts_devserver relies on ibazel to expose a livereload server. It will inject a livereload script into the page so you don't need to reload when the app is re-built.

Unit Testing

The ts_web_test rule runs the Karma test runner, configured to pick up your changes.

Like the devserver, interactive debugging of a test target is best with ibazel run, so that Karma and the browser stay running and pick up the code changes in the background.

If you run a ts_web_test target with bazel test, it will use a headless Chrome and exit after one run. This is convenient for matching lots of tests with a target pattern like bazel test //..., or on the CI.

You can try out ts_web_test by running ibazel run src/hello-world:test or bazel test src/hello-world:test

For speed, we bundle your code and other dependencies into a single JS file that's fetched to the browser where Karma's runner executes.

Attributes:

• deps are the libraries to test, typically one or more ts_library targets with testonly=1
• bootstrap is a list of files which must be loaded before the JS bundle