Bazel rules for TypeScript
This is the canonical ruleset for using Bazel with TypeScript, based on https://github.com/aspect-build/rules_js.
Many companies are successfully building with rules_ts. If you're getting value from the project, please let us know! Just comment on our Adoption Discussion.
This is a high-performance alternative to the
@bazel/typescript npm package from rules_nodejs.
ts_project rule here is identical to the one in rules_nodejs, making it easy to migrate.
Since rules_js always runs tools from the bazel-out tree, rules_ts naturally fixes most usability bugs with rules_nodejs:
- Freely mix generated
tsconfig.jsonfiles in the bazel-out tree with source files
- Fixes the need for any
tsconfig.jsonas reported in https://github.com/microsoft/TypeScript/issues/37378
- "worker mode" for
ts_projectnow shares workers across all targets, rather than requiring one worker pool per target
rules_ts is just a part of what Aspect provides:
- Need help? This ruleset has support provided by https://www.aspect.dev/bazel-open-source-support.
- See our other Bazel rules, especially those built for rules_js, linked from https://github.com/aspect-build
- Type-checking can not be performed in parallel, see --isolatedDeclarations
Follow instructions from the release you wish to use: https://github.com/aspect-build/rules_ts/releases
If you'd like an example added, you can fund a Feature Request.
See the API documentation in the docs/ folder.
From a BUILD file
The most common use is with the
ts_project macro which invokes a
transpiler you configure to transform source files like
.ts files into outputs such as
tsc CLI to type-check
the program and produce
In a macro
Many organizations set default values, so it's common to write a macro to wrap
ensure that your developers load your macro rather than loading from
BUILD file generation
Aspect provides a TypeScript BUILD file generator as part of the Aspect CLI.
aspect configure to create or update
BUILD.bazel files as you edit TypeScript sources.
Advanced: custom rules
If you know how to write Bazel rules, you might find that
ts_project doesn't do what you want.
One way to customize it is to peel off one layer of indirection, by calling the
directly. This bypasses our default setting logic, and also the validation program which checks that
ts_project attributes are well-formed.
You can also write a custom rule from scratch. We expose helper functions from /ts/private in this repo. Be aware that these are not a public API, so you may have to account for breaking changes which aren't subject to our usual semver policy.