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.
The 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
*.tsandtsconfig.jsonfiles in the bazel-out tree with source files - Fixes the need for any
rootDirssettings intsconfig.jsonas reported in microsoft/TypeScript#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
Known issues:
- 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
There are a number of examples in the examples/ folder and larger examples in the bazel-examples repository using rules_ts such as jest, react, angular.
If you'd like an example added, you can fund a Feature Request.
See the API documentation in the docs/ folder.
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 .js and .js.map,
and the tsc CLI to type-check
the program and produce .d.ts files.
Many organizations set default values, so it's common to write a macro to wrap ts_project, then
ensure that your developers load your macro rather than loading from @aspect_rules_ts directly.
Aspect provides a TypeScript BUILD file generator as part of the Aspect CLI.
Run aspect configure to create or update BUILD.bazel files as you edit TypeScript sources.
See https://docs.aspect.build/cli/commands/aspect_configure.
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 ts_project_rule
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.