WARNING: this is beta-quality software. Breaking changes are likely. Not recommended for production use without expert support.

The TypeScript rules integrate the TypeScript compiler with Bazel.

Looking for Karma rules ts_web_test and karma_web_test? These are now documented in the README at http://npmjs.com/package/@bazel/karma

This package provides Bazel wrappers around the TypeScript compiler, and are how we compile TS code at Google.

These rules are opinionated, for example:

• Your TS code must compile under the --declaration flag so that downstream libraries depend only on types, not implementation. This makes Bazel faster by avoiding cascading rebuilds in cases where the types aren't changed.
• We control the output format and module syntax so that downstream rules can rely on them.

They are also fast and optimized:

• We keep a running TypeScript compile running as a daemon, using Bazel workers. This process avoids re-parse and re-JIT of the >1MB typescript.js and keeps cached bound ASTs for input files which saves time.

We understand this is a tradeoff. If you want to use the plain TypeScript compiler provided by the TS team at Microsoft, you can do this by calling its CLI directly. For example,

load("@npm//typescript:index.bzl", "tsc")

srcs = glob(["*.ts"])
deps = ["@npm//@types/node"]

tsc(
    name = "compile",
    data = srcs + deps,
    outs = [s.replace(".ts", ext) for ext in [".js", ".d.ts"] for s in srcs],
    args = [
        "--outDir",
        "$@",
        "--lib",
        "es2017,dom",
        "--downlevelIteration",
        "--declaration",
    ] + [
        "$(location %s)" % s
        for s in srcs
    ],
)

Add a devDependency on @bazel/typescript

$ yarn add -D @bazel/typescript
# or
$ npm install --save-dev @bazel/typescript

Watch for any peerDependency warnings - we assume you have already installed the typescript package from npm.

Your WORKSPACE should declare a yarn_install or npm_install rule named npm. It should then install the rules found in the npm packages using the install_bazel_dependencies function. See https://github.com/bazelbuild/rules_nodejs/#quickstart

Add to your WORKSPACE file, after install_bazel_dependencies():

# Set up TypeScript toolchain
load("@npm_bazel_typescript//:index.bzl", "ts_setup_workspace")
ts_setup_workspace()

Create a BUILD.bazel file in your workspace root. If your tsconfig.json file is in the root, use

exports_files(["tsconfig.json"], visibility = ["//visibility:public"])

otherwise create an alias:

alias(
    name = "tsconfig.json",
    actual = "//path/to/my:tsconfig.json",
)

We recommend you use Bazel managed dependencies but if you would like Bazel to also install a node_modules in your workspace you can also point the node_repositories repository rule in your WORKSPACE file to your package.json.

node_repositories(package_json = ["//:package.json"])

You can then run yarn in your workspace with:

$ bazel run @nodejs//:yarn

To use your workspace node_modules folder as a dependency in ts_library and other rules, add the following to your root BUILD.bazel file:

filegroup(
    name = "node_modules",
    srcs = glob(
        include = [
          "node_modules/**/*.js",
          "node_modules/**/*.d.ts",
          "node_modules/**/*.json",
          "node_modules/.bin/*",
        ],
        exclude = [
          # Files under test & docs may contain file names that
          # are not legal Bazel labels (e.g.,
          # node_modules/ecstatic/test/public/中文/檔案.html)
          "node_modules/**/test/**",
          "node_modules/**/docs/**",
          # Files with spaces in the name are not legal Bazel labels
          "node_modules/**/* */**",
          "node_modules/**/* *",
        ],
    ),
)

# Create a tsc_wrapped compiler rule to use in the ts_library
# compiler attribute when using self-managed dependencies
nodejs_binary(
    name = "@bazel/typescript/tsc_wrapped",
    entry_point = "@bazel/typescript/internal/tsc_wrapped/tsc_wrapped.js",
    # Point bazel to your node_modules to find the entry point
    node_modules = ["//:node_modules"],
)

See https://github.com/bazelbuild/rules_nodejs#dependencies for more information on managing npm dependencies with Bazel.

An example use case is needing to increase the NodeJS heap size used for compilations.

Similar to above, you declare your own binary for running tsc_wrapped, e.g.:

nodejs_binary(
    name = "tsc_wrapped_bin",
    entry_point = "@npm//:node_modules/@bazel/typescript/internal/tsc_wrapped/tsc_wrapped.js",
    templated_args = [
        "--node_options=--max-old-space-size=2048",
    ],
    data = [
        "@npm//protobufjs",
        "@npm//source-map-support",
        "@npm//tsutils",
        "@npm//typescript",
        "@npm//@bazel/typescript",
    ],
)

then refer to that target in the compiler attribute of your ts_library rule.

Note that nodejs_binary targets generated by npm_install/yarn_install can include data dependencies on packages which aren't declared as dependencies. For example, if you use [tsickle] to generate Closure Compiler-compatible JS, then it needs to be a data dependency of tsc_wrapped so that it can be loaded at runtime.  [tsickle]: https://github.com/angular/tsickle

The ts_library rule invokes the TypeScript compiler on one compilation unit, or "library" (generally one directory of source files).

Create a BUILD file next to your sources:

package(default_visibility=["//visibility:public"])
load("@npm_bazel_typescript//:index.bzl", "ts_library")

ts_library(
    name = "my_code",
    srcs = glob(["*.ts"]),
    deps = ["//path/to/other:library"],
)

If your ts_library target has npm dependencies you can specify these with fine grained npm dependency targets created by the yarn_install or npm_install rules:

ts_library(
    name = "my_code",
    srcs = glob(["*.ts"]),
    deps = [
      "@npm//@types/node",
      "@npm//@types/foo",
      "@npm//foo",
      "//path/to/other:library",
    ],
)

You can also use the @npm//@types target which will include all packages in the @types scope as dependencies.

If you are using self-managed npm dependencies, you can use the node_modules attribute in ts_library and point it to the //:node_modules filegroup defined in your root BUILD.bazel file. You'll also need to override the compiler attribute if you do this as the Bazel-managed deps and self-managed cannot be used together in the same rule.

ts_library(
    name = "my_code",
    srcs = glob(["*.ts"]),
    deps = ["//path/to/other:library"],
    node_modules = "//:node_modules",
    compiler = "//:@bazel/typescript/tsc_wrapped",
)

To build a ts_library target run:

bazel build //path/to/package:target

The resulting .d.ts file paths will be printed. Additionally, the .js outputs from TypeScript will be written to disk, next to the .d.ts files ¹.

Note that the tsconfig.json file used for compilation should be the same one your editor references, to keep consistent settings for the TypeScript compiler. By default, ts_library uses the tsconfig.json file in the workspace root directory. See the notes about the tsconfig attribute in the ts_library API docs.

¹ The declarationDir compiler option will be silently overwritten if present.

The default output of the ts_library rule is the .d.ts files. This is for a couple reasons:

• help ensure that downstream rules which access default outputs will not require a cascading re-build when only the implementation changes but not the types
• make you think about whether you want the devmode (named UMD) or prodmode outputs

You can access the JS output by adding a filegroup rule after the ts_library, for example

ts_library(
    name = "compile",
    srcs = ["thing.ts"],
)

filegroup(
    name = "thing.js",
    srcs = ["compile"],
    # Change to es6_sources to get the 'prodmode' JS
    output_group = "es5_sources",
)

my_rule(
    name = "uses_js",
    deps = ["thing.js"],
)

There are two choices for development mode:

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

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

load("@npm_bazel_typescript//:index.bzl", "ts_devserver", "ts_library")

ts_library(
    name = "app",
    srcs = ["app.ts"],
)

ts_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 ts_devserver.

See 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 finishes.

Bazel's TypeScript compiler has your workspace path mapped, so you can import from an absolute path starting from your workspace.

/WORKSPACE:

workspace(name = "myworkspace")

/some/long/path/to/deeply/nested/subdirectory.ts:

import {thing} from 'myworkspace/place';

will import from /place.ts.

Since this is an extension to the vanillia TypeScript compiler, editors which use the TypeScript language services to provide code completion and inline type checking will not be able to resolve the modules. In the above example, adding

"paths": {
    "myworkspace/*": ["*"]
}

to tsconfig.json will fix the imports for the common case of using absolute paths. See path mapping for more details on the paths syntax.

Similarly, you can use path mapping to teach the editor how to resolve imports from ts_library rules which set the module_name attribute.

If you'd like a "watch mode", try ibazel.

At some point, we plan to release a tool similar to gazelle to generate the BUILD files from your source code.

Allows a tsconfig.json file to extend another file.

Normally, you just give a single tsconfig.json file as the tsconfig attribute of a ts_library rule. However, if your tsconfig.json uses the extends feature from TypeScript, then the Bazel implementation needs to know about that extended configuration file as well, to pass them both to the TypeScript compiler.

ts_config(name, deps, src)

(name, mandatory): A unique name for this target.

(labels, mandatory): Additional tsconfig.json files referenced via extends

(label, mandatory): The tsconfig.json file passed to the TypeScript compiler

ts_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

ts_devserver(name, additional_root_paths, bootstrap, data, deps, devserver, entry_module, index_html, port, scripts, serving_path, static_files)

(name, mandatory): A unique name for this target.

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

(labels): Scripts to include in the JS bundle before the module loader (require.js)

(labels): Dependencies that can be require'd while the server is running

(labels): Targets that produce JavaScript, such as ts_library

(label): Go based devserver executable. Defaults to precompiled go binary in @npm_bazel_typescript setup by @bazel/typescript npm package

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

(label): An index.html file, we'll inject the script tag for the bundle, as well as script tags for .js static_files and link tags for .css static_files

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

(labels): User scripts to include in the JS bundle before the application sources

(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

(labels): Arbitrary files which to be served, such as index.html. They are served relative to the package where this rule is declared.

ts_library type-checks and compiles a set of TypeScript sources to JavaScript.

It produces declarations files (.d.ts) which are used for compiling downstream TypeScript targets and JavaScript for the browser and Closure compiler.

ts_library(name, compile_angular_templates, compiler, data, deps, expected_diagnostics, generate_externs, internal_testing_type_check_dependencies, module_name, module_root, node_modules, runtime, runtime_deps, srcs, supports_workers, tsconfig, tsickle_typed)

(name, mandatory): A unique name for this target.

(Boolean): Run the Angular ngtsc compiler under ts_library

(label): Sets a different TypeScript compiler binary to use for this library. For example, we use the vanilla TypeScript tsc.js for bootstrapping, and Angular compilations can replace this with ngc.

The default ts_library compiler depends on the @npm//@bazel/typescript target which is setup for projects that use bazel managed npm deps that fetch the @bazel/typescript npm package. It is recommended that you use the workspace name @npm for bazel managed deps so the default compiler works out of the box. Otherwise, you'll have to override the compiler attribute manually.

(labels)

(labels): Compile-time dependencies, typically other ts_library targets

(List of strings)

(Boolean)

(Boolean): Testing only, whether to type check inputs that aren't srcs.

(String)

(String)

(label): The npm packages which should be available during the compile.

The default value is @npm//typescript:typescript__typings is setup for projects that use bazel managed npm deps that. It is recommended that you use the workspace name @npm for bazel managed deps so the default node_modules works out of the box. Otherwise, you'll have to override the node_modules attribute manually. This default is in place since ts_library will always depend on at least the typescript default libs which are provided by @npm//typescript:typescript__typings.

This attribute is DEPRECATED. As of version 0.18.0 the recommended approach to npm dependencies is to use fine grained npm dependencies which are setup with the yarn_install or npm_install rules.

For example, in targets that used a //:node_modules filegroup,

ts_library(
    name = "my_lib",
    ...
    node_modules = "//:node_modules",
)

which specifies all files within the //:node_modules filegroup to be inputs to the my_lib. Using fine grained npm dependencies, my_lib is defined with only the npm dependencies that are needed:

ts_library(
    name = "my_lib",
    ...
    deps = [
        "@npm//@types/foo",
        "@npm//@types/bar",
        "@npm//foo",
        "@npm//bar",
        ...
    ],
)

In this case, only the listed npm packages and their transitive deps are includes as inputs to the my_lib target which reduces the time required to setup the runfiles for this target (see bazelbuild/bazel#5153). The default typescript libs are also available via the node_modules default in this case.

The @npm external repository and the fine grained npm package targets are setup using the yarn_install or npm_install rule in your WORKSPACE file:

yarn_install(
    name = "npm",
    package_json = "//:package.json",
    yarn_lock = "//:yarn.lock",
)

(String)

(labels)

(labels, mandatory): The TypeScript source files to compile.

(Boolean): Intended for internal use only.

Allows you to disable the Bazel Worker strategy for this library. Typically used together with the "compiler" setting when using a non-worker aware compiler binary.

(label): A tsconfig.json file containing settings for TypeScript compilation. Note that some properties in the tsconfig are governed by Bazel and will be overridden, such as target and module.

The default value is set to //:tsconfig.json by a macro. This means you must either:

• Have your tsconfig.json file in the workspace root directory
• Use an alias in the root BUILD.bazel file to point to the location of tsconfig: alias(name="tsconfig.json", actual="//path/to:tsconfig-something.json")
• Give an explicit tsconfig attribute to all ts_library targets

(Boolean): If using tsickle, instruct it to translate types to ClosureJS format

This repository rule should be called from your WORKSPACE file.

It creates some additional Bazel external repositories that are used internally by the TypeScript rules.

ts_setup_workspace()