Skip to main content
Version: 1.2.x

Public API for TypeScript rules

The most commonly used is the ts_project macro which accepts TypeScript sources as inputs and produces JavaScript or declaration (.d.ts) outputs.

Rules

ts_config

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

Example usage (generated):

load("@aspect_rules_ts//ts:defs.bzl", "ts_config")

ts_config(
# A unique name for this target.
name = "",
# The tsconfig.json file passed to the TypeScript compiler
src = "",
)

name

Required name.

A unique name for this target.

deps

Optional list of labels. Default: []

Additional tsconfig.json files referenced via extends

src

Required label.

The tsconfig.json file passed to the TypeScript compiler

ts_project_rule

Implementation rule behind the ts_project macro. Most users should use ts_project instead.

This skips conveniences like validation of the tsconfig attributes, default settings for srcs and tsconfig, and pre-declaring output files.

Example usage (generated):

load("@aspect_rules_ts//ts:defs.bzl", "ts_project_rule")

ts_project_rule(
# A unique name for this target.
name = "",
# TypeScript source files
srcs = [],
# TypeScript compiler binary
tsc = "",
# TypeScript compiler worker binary
tsc_worker = "",
# tsconfig.json file, see https://www.typescriptlang.org/tsconfig
tsconfig = "",
)

name

Required name.

A unique name for this target.

allow_js

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#allowJs

args

Optional list of strings. Default: []

https://www.typescriptlang.org/docs/handbook/compiler-options.html

assets

Optional list of labels. Default: []

Files which are needed by a downstream build step such as a bundler. See more details on the assets parameter of the ts_project macro.

buildinfo_out

Optional label.

Location in bazel-out where tsc will write a .tsbuildinfo file

composite

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#composite

data

Optional list of labels. Default: []

Runtime dependencies to include in binaries/tests that depend on this target.

The transitive npm dependencies, transitive sources, default outputs and runfiles of targets in the data attribute are added to the runfiles of this target. They should appear in the '*.runfiles' area of any executable which has a runtime dependency on this target.

If this list contains linked npm packages, npm package store targets or other targets that provide JsInfo, NpmPackageStoreInfo providers are gathered from JsInfo. This is done directly from the npm_package_store_deps field of these. For linked npm package targets, the underlying npm_package_store target(s) that back the links is used.

Gathered NpmPackageStoreInfo providers are used downstream as direct dependencies when linking a downstream npm_package target with npm_link_package.

declaration

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#declaration

declaration_dir

Optional string. Default: ""

https://www.typescriptlang.org/tsconfig#declarationDir

declaration_map

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#declarationMap

deps

Optional list of labels. Default: []

[Must provide JsInfo][Must provide `ValidOptionsInfo`]

Other targets which produce TypeScript typings

emit_declaration_only

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#emitDeclarationOnly

extends

Optional label. Default: None

https://www.typescriptlang.org/tsconfig#extends

incremental

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#incremental

js_outs

Optional list of labels.

Locations in bazel-out where tsc will write .js files

map_outs

Optional list of labels.

Locations in bazel-out where tsc will write .js.map files

out_dir

Optional string. Default: ""

https://www.typescriptlang.org/tsconfig#outDir

preserve_jsx

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#jsx

resolve_json_module

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#resolveJsonModule

root_dir

Optional string. Default: ""

https://www.typescriptlang.org/tsconfig#rootDir

source_map

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#sourceMap

srcs

Required list of labels.

TypeScript source files

supports_workers

Optional boolean. Default: False

Whether the tsc compiler understands Bazel's persistent worker protocol

transpile

Optional boolean. Default: True

whether tsc should be used to produce .js outputs

tsc

Required label.

TypeScript compiler binary

tsc_worker

Required label.

TypeScript compiler worker binary

tsconfig

Required label.

tsconfig.json file, see https://www.typescriptlang.org/tsconfig

typing_maps_outs

Optional list of labels.

Locations in bazel-out where tsc will write .d.ts.map files

typings_outs

Optional list of labels.

Locations in bazel-out where tsc will write .d.ts files

validate_options

Validates that some tsconfig.json properties match attributes on ts_project. See the documentation of ts_project for more information.

Example usage (generated):

load("@aspect_rules_ts//ts:defs.bzl", "validate_options")

validate_options(
# A unique name for this target.
name = "",
deps = [],
tsconfig = "",
validator = "",
)

name

Required name.

A unique name for this target.

allow_js

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#allowJs

composite

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#composite

declaration

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#declaration

declaration_map

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#declarationMap

deps

Required list of labels.

[Must provide JsInfo]

emit_declaration_only

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#emitDeclarationOnly

extends

Optional label. Default: None

https://www.typescriptlang.org/tsconfig#extends

incremental

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#incremental

preserve_jsx

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#jsx

resolve_json_module

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#resolveJsonModule

source_map

Optional boolean. Default: False

https://www.typescriptlang.org/tsconfig#sourceMap

target

Optional string. Default: ""

ts_build_info_file

Optional string. Default: ""

tsconfig

Required label.

validator

Required label.

Macros and Functions

ts_project

Compiles one TypeScript project using tsc --project.

This is a drop-in replacement for the tsc rule automatically generated for the "typescript" package, typically loaded from @npm//typescript:package_json.bzl. Unlike bare tsc, this rule understands the Bazel interop mechanism (Providers) so that this rule works with others that produce or consume TypeScript typings (.d.ts files).

One of the benefits of using ts_project is that it understands the Bazel Worker Protocol which makes the overhead of starting the compiler be a one-time cost. Worker mode is on by default to speed up build and typechecking process.

Some TypeScript options affect which files are emitted, and Bazel needs to predict these ahead-of-time. As a result, several options from the tsconfig file must be mirrored as attributes to ts_project. A validator action is run to help ensure that these are correctly mirrored. See https://www.typescriptlang.org/tsconfig for a listing of the TypeScript options.

If you have problems getting your ts_project to work correctly, read the dedicated troubleshooting guide.

Example usage (generated):

load("@aspect_rules_ts//ts:defs.bzl", "ts_project")

ts_project(
# a name for this target
name = "",
)

name

Required.

a name for this target

tsconfig

Optional. Default: None

Label of the tsconfig.json file to use for the compilation. To support "chaining" of more than one extended config, this label could be a target that provides TsConfigInfo such as ts_config.

By default, if a "tsconfig.json" file is in the same folder with the ts_project rule, it is used.

Instead of a label, you can pass a dictionary matching the JSON schema.

See docs/tsconfig.md for detailed information.

srcs

Optional. Default: None

List of labels of TypeScript source files to be provided to the compiler.

If absent, the default is set as follows:

  • Include all TypeScript files in the package, recursively.
  • If allow_js is set, include all JavaScript files in the package as well.
  • If resolve_json_module is set, include all JSON files in the package, but exclude package.json, package-lock.json, and tsconfig*.json.

args

Optional. Default: []

List of strings of additional command-line arguments to pass to tsc. See https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options Typically useful arguments for debugging are --listFiles and --listEmittedFiles.

data

Optional. Default: []

Files needed at runtime by binaries or tests that transitively depend on this target. See https://bazel.build/reference/be/common-definitions#typical-attributes

deps

Optional. Default: []

List of labels of other rules that produce TypeScript typings (.d.ts files)

assets

Optional. Default: []

Files which are needed by a downstream build step such as a bundler.

These files are not included as inputs to any actions spawned by ts_project. They are not transpiled, and are not visible to the type-checker. Instead, these files appear among the outputs of this target.

A typical use is when your TypeScript code has an import that TS itself doesn't understand such as

import './my.scss'

and the type-checker allows this because you have an "ambient" global type declaration like

declare module '*.scss' { ... }

A bundler like webpack will expect to be able to resolve the ./my.scss import to a file and doesn't care about the typing declaration. A bundler runs as a build step, so it does not see files included in the data attribute.

Note that data is used for files that are resolved by some binary, including a test target. Behind the scenes, data populates Bazel's Runfiles object in DefaultInfo, while this attribute populates the transitive_sources of the JsInfo.

extends

Optional. Default: None

Label of the tsconfig file referenced in the extends section of tsconfig To support "chaining" of more than one extended config, this label could be a target that provdes TsConfigInfo such as ts_config.

allow_js

Optional. Default: False

Whether TypeScript will read .js and .jsx files. When used with declaration, TypeScript will generate .d.ts files from .js files.

declaration

Optional. Default: False

Whether the declaration bit is set in the tsconfig. Instructs Bazel to expect a .d.ts output for each .ts source.

source_map

Optional. Default: False

Whether the sourceMap bit is set in the tsconfig. Instructs Bazel to expect a .js.map output for each .ts source.

declaration_map

Optional. Default: False

Whether the declarationMap bit is set in the tsconfig. Instructs Bazel to expect a .d.ts.map output for each .ts source.

resolve_json_module

Optional. Default: None

Boolean; specifies whether TypeScript will read .json files. If set to True or False and tsconfig is a dict, resolveJsonModule is set in the generated config file. If set to None and tsconfig is a dict, resolveJsonModule is unset in the generated config and typescript default or extended tsconfig value will be load bearing.

preserve_jsx

Optional. Default: False

Whether the jsx value is set to "preserve" in the tsconfig. Instructs Bazel to expect a .jsx or .jsx.map output for each .tsx source.

composite

Optional. Default: False

Whether the composite bit is set in the tsconfig. Instructs Bazel to expect a .tsbuildinfo output and a .d.ts output for each .ts source.

incremental

Optional. Default: False

Whether the incremental bit is set in the tsconfig. Instructs Bazel to expect a .tsbuildinfo output.

emit_declaration_only

Optional. Default: False

Whether the emitDeclarationOnly bit is set in the tsconfig. Instructs Bazel not to expect .js or .js.map outputs for .ts sources.

transpiler

Optional. Default: None

A custom transpiler tool to run that produces the JavaScript outputs instead of tsc.

By default, ts_project expects .js outputs to be written in the same action that does the type-checking to produce .d.ts outputs. This is the simplest configuration, however tsc is slower than alternatives. It also means developers must wait for the type-checking in the developer loop.

See docs/transpiler.md for more details.

ts_build_info_file

Optional. Default: None

The user-specified value of tsBuildInfoFile from the tsconfig. Helps Bazel to predict the path where the .tsbuildinfo output is written.

tsc

Optional. Default: "@npm_typescript//:tsc"

Label of the TypeScript compiler binary to run. This allows you to use a custom API-compatible compiler in place of the regular tsc such as a custom js_binary or Angular's ngc. compatible with it such as Angular's ngc.

See examples of use in examples/custom_compiler

tsc_worker

Optional. Default: "@npm_typescript//:tsc_worker"

Label of a custom TypeScript compiler binary which understands Bazel's persistent worker protocol.

validate

Optional. Default: True

Whether to check that the dependencies are valid and the tsconfig JSON settings match the attributes on this target. Set this to False to skip running our validator, in case you have a legitimate reason for these to differ, e.g. you have a setting enabled just for the editor but you want different behavior when Bazel runs tsc.

validator

Optional. Default: "@npm_typescript//:validator"

Label of the tsconfig validator to run when validate = True.

declaration_dir

Optional. Default: None

String specifying a subdirectory under the bazel-out folder where generated declaration outputs are written. Equivalent to the TypeScript --declarationDir option. By default declarations are written to the out_dir.

out_dir

Optional. Default: None

String specifying a subdirectory under the bazel-out folder where outputs are written. Equivalent to the TypeScript --outDir option.

Note that Bazel always requires outputs be written under a subdirectory matching the input package, so if your rule appears in path/to/my/package/BUILD.bazel and out_dir = "foo" then the .js files will appear in bazel-out/[arch]/bin/path/to/my/package/foo/*.js.

By default the out_dir is the package's folder under bazel-out.

root_dir

Optional. Default: None

String specifying a subdirectory under the input package which should be consider the root directory of all the input files. Equivalent to the TypeScript --rootDir option. By default it is '.', meaning the source directory where the BUILD file lives.

supports_workers

Optional. Default: True

Whether the worker protocol is enabled. To disable worker mode for a particular target set supports_workers to False. Worker mode can be controlled as well via --strategy and mnemonic and using .bazelrc.

Put this in your .bazelrc to disable it globally: build --strategy=TsProject=sandboxed

See https://docs.bazel.build/versions/main/user-manual.html#flag--strategy for more details.

kwargs

Optional.

passed through to underlying ts_project_rule, eg. visibility, tags

Providers

TsConfigInfo

Provides TypeScript configuration, in the form of a tsconfig.json file along with any transitively referenced tsconfig.json files chained by the "extends" feature