rules_ts
v3.3.1
published 2 weeks ago
106 stars
63 forks
5 watchers
aspect-build/rules_ts
Apache License 2.0
public
1 assets
6,188,589 downloads
124 KB
Bazel central registry
Compatability level 1
ms0Sir53OXUFFI6qaJX67VeDlWDb8hd91iheUSNeJyQ=
Maintained byGreg Magolan,Jason Bedard,Sahin Yort
Bazel rules for the `tsc` compiler from http://typescriptlang.org
v3.3.1
November 5, 2024

Using Bzlmod with Bazel 6:

Add to your MODULE.bazel file:

bazel_dep(name = "aspect_rules_ts", version = "3.3.1")

rules_ts_ext = use_extension("@aspect_rules_ts//ts:extensions.bzl", "ext", dev_dependency = True)

rules_ts_ext.deps(
    ts_version_from = "//:package.json",
)

use_repo(rules_ts_ext, "npm_typescript")

Using WORKSPACE

Paste this snippet into your WORKSPACE file:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "aspect_rules_ts",
    sha256 = "9acd128abe77397505148eaa6895faed57839560dbf2177dd6285e51235e2724",
    strip_prefix = "rules_ts-3.3.1",
    url = "https://github.com/aspect-build/rules_ts/releases/download/v3.3.1/rules_ts-v3.3.1.tar.gz",
)

##################
# rules_ts setup #
##################
# Fetches the rules_ts dependencies.
# If you want to have a different version of some dependency,
# you should fetch it *before* calling this.
# Alternatively, you can skip calling this function, so long as you've
# already fetched all the dependencies.
load("@aspect_rules_ts//ts:repositories.bzl", "rules_ts_dependencies")

rules_ts_dependencies(
    # This keeps the TypeScript version in-sync with the editor, which is typically best.
    ts_version_from = "//:package.json",

    # Alternatively, you could pick a specific version, or use
    # load("@aspect_rules_ts//ts:repositories.bzl", "LATEST_TYPESCRIPT_VERSION")
    # ts_version = LATEST_TYPESCRIPT_VERSION
)

load("@aspect_rules_js//js:repositories.bzl", "rules_js_dependencies")

rules_js_dependencies()

load("@aspect_rules_js//js:toolchains.bzl", "DEFAULT_NODE_VERSION", "rules_js_register_toolchains")

rules_js_register_toolchains(node_version = DEFAULT_NODE_VERSION)

# Register aspect_bazel_lib toolchains;
# If you use npm_translate_lock or npm_import from aspect_rules_js you can omit this block.
load("@aspect_bazel_lib//lib:repositories.bzl", "register_copy_directory_toolchains", "register_copy_to_directory_toolchains")

register_copy_directory_toolchains()

register_copy_to_directory_toolchains()

To use rules_ts with bazel-lib 2.x, you must additionally register the coreutils toolchain.

load("@aspect_bazel_lib//lib:repositories.bzl", "register_coreutils_toolchains")

register_coreutils_toolchains()

What's Changed

Full Changelog: https://github.com/aspect-build/rules_ts/compare/v3.3.0...v3.3.1

Deps:
Assets:

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. 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 *.ts and tsconfig.json files in the bazel-out tree with source files
  • Fixes the need for any rootDirs settings in tsconfig.json as reported in microsoft/TypeScript#37378
  • "worker mode" for ts_project now shares workers across all targets, rather than requiring one worker pool per target

rules_ts is just a part of what Aspect provides:

Known issues:

Installation

Follow instructions from the release you wish to use: https://github.com/aspect-build/rules_ts/releases

Examples

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.

Usage

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 .js and .js.map, and the tsc CLI to type-check the program and produce .d.ts files.

In a macro

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.

BUILD file generation

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.

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