Skip to content

Latest commit

 

History

History
217 lines (165 loc) · 26.7 KB

rules.md

File metadata and controls

217 lines (165 loc) · 26.7 KB
Raw

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.

ts_config

ts_config(name, deps, src)

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.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Additional tsconfig.json files referenced via extends List of labels optional []
src The tsconfig.json file passed to the TypeScript compiler Label required

ts_project_rule

ts_project_rule(name, deps, srcs, data, allow_js, args, assets, buildinfo_out, composite,
                declaration, declaration_dir, declaration_map, emit_declaration_only, extends,
                incremental, is_typescript_5_or_greater, js_outs, map_outs, out_dir, preserve_jsx,
                resolve_json_module, root_dir, source_map, supports_workers, transpile,
                ts_build_info_file, tsc, tsc_worker, tsconfig, typing_maps_outs, typings_outs,
                validate, validator)

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.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of targets that produce TypeScript typings (.d.ts files)

Follows the same runfiles semantics as js_library deps attribute. See https://docs.aspect.build/rulesets/aspect_rules_js/docs/js_library#deps for more info.		 List of labels optional []
srcs TypeScript source files List of labels required
data Runtime dependencies to include in binaries/tests that depend on this target.

Follows the same semantics as js_library data attribute. See https://docs.aspect.build/rulesets/aspect_rules_js/docs/js_library#data for more info.		 List of labels optional []
allow_js https://www.typescriptlang.org/tsconfig#allowJs Boolean optional False
args https://www.typescriptlang.org/docs/handbook/compiler-options.html List of strings optional []
assets 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.		 List of labels optional []
buildinfo_out Location in bazel-out where tsc will write a .tsbuildinfo file Label optional None
composite https://www.typescriptlang.org/tsconfig#composite Boolean optional False
declaration https://www.typescriptlang.org/tsconfig#declaration Boolean optional False
declaration_dir https://www.typescriptlang.org/tsconfig#declarationDir String optional ""
declaration_map https://www.typescriptlang.org/tsconfig#declarationMap Boolean optional False
emit_declaration_only https://www.typescriptlang.org/tsconfig#emitDeclarationOnly Boolean optional False
extends https://www.typescriptlang.org/tsconfig#extends Label optional None
incremental https://www.typescriptlang.org/tsconfig#incremental Boolean optional False
is_typescript_5_or_greater Whether TypeScript version is >= 5.0.0 Boolean optional False
js_outs Locations in bazel-out where tsc will write .js files List of labels optional []
map_outs Locations in bazel-out where tsc will write .js.map files List of labels optional []
out_dir https://www.typescriptlang.org/tsconfig#outDir String optional ""
preserve_jsx https://www.typescriptlang.org/tsconfig#jsx Boolean optional False
resolve_json_module https://www.typescriptlang.org/tsconfig#resolveJsonModule Boolean optional False
root_dir https://www.typescriptlang.org/tsconfig#rootDir String optional ""
source_map https://www.typescriptlang.org/tsconfig#sourceMap Boolean optional False
supports_workers Whether to use a custom tsc compiler which understands Bazel's persistent worker protocol.

See the docs for supports_workers on the ts_project macro.		 Integer optional 0
transpile Whether tsc should be used to produce .js outputs

Values are: - -1: Error if --@aspect_rules_ts//ts:default_to_tsc_transpiler not set, otherwise transpile - 0: Do not transpile - 1: Transpile		 Integer optional -1
ts_build_info_file https://www.typescriptlang.org/tsconfig#tsBuildInfoFile String optional ""
tsc TypeScript compiler binary Label required
tsc_worker TypeScript compiler worker binary Label required
tsconfig tsconfig.json file, see https://www.typescriptlang.org/tsconfig Label required
typing_maps_outs Locations in bazel-out where tsc will write .d.ts.map files List of labels optional []
typings_outs Locations in bazel-out where tsc will write .d.ts files List of labels optional []
validate whether to add a Validation Action to verify the other attributes match settings in the tsconfig.json file Boolean optional True
validator - Label required

validate_options

validate_options(name, deps, allow_js, composite, declaration, declaration_map,
                 emit_declaration_only, extends, incremental, preserve_jsx, resolve_json_module,
                 source_map, target, ts_build_info_file, tsconfig, validator)

DEPRECATED. Use Validation Actions instead.

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

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps - List of labels required
allow_js https://www.typescriptlang.org/tsconfig#allowJs Boolean optional False
composite https://www.typescriptlang.org/tsconfig#composite Boolean optional False
declaration https://www.typescriptlang.org/tsconfig#declaration Boolean optional False
declaration_map https://www.typescriptlang.org/tsconfig#declarationMap Boolean optional False
emit_declaration_only https://www.typescriptlang.org/tsconfig#emitDeclarationOnly Boolean optional False
extends https://www.typescriptlang.org/tsconfig#extends Label optional None
incremental https://www.typescriptlang.org/tsconfig#incremental Boolean optional False
preserve_jsx https://www.typescriptlang.org/tsconfig#jsx Boolean optional False
resolve_json_module https://www.typescriptlang.org/tsconfig#resolveJsonModule Boolean optional False
source_map https://www.typescriptlang.org/tsconfig#sourceMap Boolean optional False
target - String optional ""
ts_build_info_file - String optional ""
tsconfig - Label required
validator - Label required

TsConfigInfo

TsConfigInfo(deps)

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

FIELDS

Name Description
deps all tsconfig.json files needed to configure TypeScript

ts_project

ts_project(name, tsconfig, srcs, args, data, deps, assets, extends, allow_js, declaration,
           source_map, declaration_map, resolve_json_module, preserve_jsx, composite, incremental,
           emit_declaration_only, transpiler, ts_build_info_file, tsc, tsc_worker, validate,
           validator, declaration_dir, out_dir, root_dir, supports_workers, kwargs)

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

PARAMETERS

Name Description Default Value
name a name for this target none
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 matching the JSON schema.

See docs/tsconfig.md for detailed information.		 None
srcs 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.		 None
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 targets that produce TypeScript typings (.d.ts files)

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 propagated to the direct dependencies of downstream linked npm_package targets.

NB: Linked npm package targets that are "dev" dependencies do not forward their underlying npm_package_store target(s) through npm_package_store_deps and will therefore not be propagated to the direct dependencies of downstream linked npm_package targets. npm packages that come in from npm_translate_lock are considered "dev" dependencies if they are have dev: true set in the pnpm lock file. This should be all packages that are only listed as "devDependencies" in all package.json files within the pnpm workspace. This behavior is intentional to mimic how devDependencies work in published npm packages.		 []
assets 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 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. None
allow_js Whether TypeScript will read .js and .jsx files. When used with declaration, TypeScript will generate .d.ts files from .js files. False
declaration Whether the declaration bit is set in the tsconfig. Instructs Bazel to expect a .d.ts output for each .ts source. False
source_map Whether the sourceMap bit is set in the tsconfig. Instructs Bazel to expect a .js.map output for each .ts source. False
declaration_map Whether the declarationMap bit is set in the tsconfig. Instructs Bazel to expect a .d.ts.map output for each .ts source. False
resolve_json_module 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. None
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. False
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. False
incremental Whether the incremental bit is set in the tsconfig. Instructs Bazel to expect a .tsbuildinfo output. False
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. False
transpiler A custom transpiler tool to run that produces the JavaScript outputs instead of tsc.

Under --@aspect_rules_ts//ts:default_to_tsc_transpiler, the default is to use tsc to produce .js outputs 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.

Without --@aspect_rules_ts//ts:default_to_tsc_transpiler, an explicit value must be set. This may be the string "tsc" to explicitly choose tsc, just like the default above.

It may also be any rule or macro with this signature: (name, srcs, **kwargs)

See docs/transpiler.md for more details.		 None
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. None
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		 "@npm_typescript//:tsc"
tsc_worker Label of a custom TypeScript compiler binary which understands Bazel's persistent worker protocol. "@npm_typescript//:tsc_worker"
validate 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. True
validator Label of the tsconfig validator to run when validate = True. "@npm_typescript//:validator"
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. None
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 the package's folder under bazel-out.		 None
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. None
supports_workers Whether the "Persistent Worker" protocol is enabled. This uses a custom tsc compiler to make rebuilds faster. Note that this causes some known correctness bugs, see https://docs.aspect.build/rules/aspect_rules_ts/docs/troubleshooting. We do not intend to fix these bugs.

Worker mode can be enabled for all ts_projects in a build with the global --@aspect_rules_ts//ts:supports_workers flag. To enable worker mode for all builds in the workspace, add build --@aspect_rules_ts//ts:supports_workers to the .bazelrc.

This is a "tri-state" attribute, accepting values [-1, 0, 1]. The behavior is:

- -1: use the value of the global --@aspect_rules_ts//ts:supports_workers flag. - 0: Override the global flag, disabling workers for this target. - 1: Override the global flag, enabling workers for this target.		 -1
kwargs passed through to underlying ts_project_rule, eg. visibility, tags none