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.6.1",
)

load("@build_bazel_rules_typescript//:defs.bzl", "ts_repositories")

ts_repositories()

Finally, be sure you added the --strategy settings above to your bazelrc 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.

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 bazel run (or ibazel run in watch mode).

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.