Public API for TypeScript rules
Nearly identical to the ts_project wrapper macro in npm @bazel/typescript. Differences:
- uses the executables from @npm_typescript rather than what a user npm_install'ed
- didn't copy the whole doc string
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("@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
A unique name for this target.
deps
Additional tsconfig.json files referenced via extends
src
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.
Example usage (generated)
load("@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
A unique name for this target.
allow_js
args
https://www.typescriptlang.org/docs/handbook/compiler-options.html
buildinfo_out
Location in bazel-out where tsc will write a .tsbuildinfo
file
composite
data
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 taregt. Thery 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 npm_package_stores
and
transitive_npm_package_stores
fields of these and for linked npm package targets, from the underlying
npm_package_store target(s) that back the links via npm_linked_packages
and transitive_npm_linked_packages
.
Gathered NpmPackageStoreInfo
providers are used downstream as direct dependencies when linking a downstream
npm_package
target with npm_link_package
.
declaration
declaration_dir
declaration_map
deps
Other targets which produce TypeScript typings
emit_declaration_only
extends
incremental
js_outs
Locations in bazel-out where tsc will write .js
files
map_outs
Locations in bazel-out where tsc will write .js.map
files
out_dir
preserve_jsx
resolve_json_module
root_dir
source_map
srcs
TypeScript source files
supports_workers
Whether the tsc compiler understands Bazel's persistent worker protocol
transpile
whether tsc should be used to produce .js outputs
tsc
TypeScript compiler binary
tsc_worker
TypeScript compiler worker binary
tsconfig
tsconfig.json file, see https://www.typescriptlang.org/tsconfig
typing_maps_outs
Locations in bazel-out where tsc will write .d.ts.map
files
typings_outs
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("@rules_ts//ts:defs.bzl", "validate_options")
validate_options(
# A unique name for this target.
name = "",
tsconfig = "",
validator = "",
)
name
A unique name for this target.
allow_js
composite
declaration
declaration_map
emit_declaration_only
extends
has_local_deps
Whether any of the deps are in the local workspace
incremental
preserve_jsx
resolve_json_module
source_map
target
ts_build_info_file
tsconfig
validator
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 Bazel Worker Protocol which makes JIT overhead 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.
Any code that works with tsc
should work with ts_project
with a few caveats:
- ts_project
always produces some output files, or else Bazel would never run it. Therefore you shouldn't use it with TypeScript's
noEmit` option. If you only want to test that the code typechecks, instead useload("@npm//typescript:package_json.bzl", "bin") bin.tsc_test( ... )
- Your tsconfig settings for
outDir
anddeclarationDir
are ignored. Bazel requires that theoutDir
(anddeclarationDir
) be set beneathbazel-out/[target architecture]/bin/path/to/package
. - Bazel expects that each output is produced by a single rule.
Thus if you have two
ts_project
rules with overlapping sources (the same.ts
file appears in more than one) then you get an error about conflicting.js
output files if you try to build both together. Worse, if you build them separately then the output directory will contain whichever one you happened to build most recently. This is highly discouraged.
Example usage (generated)
load("@rules_ts//ts:defs.bzl", "ts_project")
ts_project(
# a name for this target
name = "",
)
name
a name for this target
tsconfig
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 of tsconfig keys. In this case, a tsconfig.json file will be generated for this compilation, in the following way:
- all top-level keys will be copied by converting the dict to json.
So
tsconfig = {"compilerOptions": {"declaration": True}}
will result in a generatedtsconfig.json
with{"compilerOptions": {"declaration": true}}
- each file in srcs will be converted to a relative path in the
files
section. - the
extends
attribute will be converted to a relative path Note that you can mix and match attributes and compilerOptions properties, so these are equivalent:
andts_project( tsconfig = { "compilerOptions": { "declaration": True, }, }, )
ts_project( declaration = True, )
srcs
List of labels of TypeScript source files to be provided to the compiler.
If absent, the default is set as follows:
- Include
**/*.ts[x]
(all TypeScript files in the package). - If
allow_js
is set, include**/*.js[x]
(all JavaScript files in the package). - If
resolve_json_module
is set, include**/*.json
(all JSON files in the package), but exclude**/package.json
,**/package-lock.json
, and**/tsconfig*.json
.
args
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
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
List of labels of other rules that produce TypeScript typings (.d.ts files)
extends
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
Whether TypeScript will read .js and .jsx files.
When used with declaration
, TypeScript will generate .d.ts
files from .js
files.
declaration
Whether the declaration
bit is set in the tsconfig.
Instructs Bazel to expect a .d.ts
output for each .ts
source.
source_map
Whether the sourceMap
bit is set in the tsconfig.
Instructs Bazel to expect a .js.map
output for each .ts
source.
declaration_map
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
None | Boolean; Specifies whether TypeScript will read .json files. Defaults to None. 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
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
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
Whether the incremental
bit is set in the tsconfig.
Instructs Bazel to expect a .tsbuildinfo
output.
emit_declaration_only
Whether the emitDeclarationOnly
bit is set in the tsconfig.
Instructs Bazel not to expect .js
or .js.map
outputs for .ts
sources.
transpiler
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.
This attribute accepts a rule or macro with this signature:
name, srcs, js_outs, map_outs, **kwargs
where the **kwargs
attribute propagates the tags, visibility, and testonly attributes from ts_project
.
If you need to pass additional attributes to the transpiler rule, you can use a
partial
to bind those arguments at the "make site", then pass that partial to this attribute where it
will be called with the remaining arguments.
See the packages/typescript/test/ts_project/swc directory for an example.
When a custom transpiler is used, then the ts_project
macro expands to these targets:
[name]
- the default target which can be included in thedeps
of downstream rules. Note that it will successfully build even if there are typecheck failures because thetsc
binary is not needed to produce the default outputs. This is considered a feature, as it allows you to have a faster development mode where type-checking is not on the critical path.[name]_typecheck
- provides typings (.d.ts
files) as the default output, therefore building this target always causes the typechecker to run.[name]_typecheck_test
- abuild_test
target which simply depends on the[name]_typecheck
target. This ensures that typechecking will be run underbazel test
with--build_tests_only
.[name]_typings
- internal target which runs the binary from thetsc
attribute- Any additional target(s) the custom transpiler rule/macro produces. Some rules produce one target per TypeScript input file.
Read more: https://blog.aspect.dev/typescript-speedup
ts_build_info_file
The user-specified value of tsBuildInfoFile
from the tsconfig.
Helps Bazel to predict the path where the .tsbuildinfo output is written.
tsc
Label of the TypeScript compiler binary to run. This allows you to use a custom compiler.
tsc_worker
Label of a custom TypeScript compiler binary which understands Bazel's persistent worker protocol.
validate
Whether to check that 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
Label of the tsconfig validator to run when validate = True
.
declaration_dir
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
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 '.', meaning the packages folder in bazel-out.
root_dir
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
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.
Putting this to your .bazelrc will disable it globally.
build --strategy=TsProject=sandboxed
Checkout https://docs.bazel.build/versions/main/user-manual.html#flag--strategy for more
kwargs
passed through to underlying ts_project_rule
, eg. visibility
, tags