This contains references to the symbols we want documented.
We can't point stardoc to the top-level index.bzl since then it will see macros rather than the rules they wrap. So this is a copy of index.bzl with macro indirection removed.
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.
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_devserver
ts_devserver is a simple development server intended for a quick "getting started" experience.
Additional documentation here
name
A unique name for this target.
additional_root_paths
Additional root paths to serve static_files
from.
Paths should include the workspace name such as ["__main__/resources"]
bootstrap
Scripts to include in the JS bundle before the module loader (require.js)
deps
Targets that produce JavaScript, such as ts_library
devserver
Go based devserver executable.
With cross-platform RBE for OSX & Windows ctx.executable.devserver will be linux as --cpu and --host_cpu must be overridden to k8. However, we still want to be able to run the devserver on the host machine so we need to include the host devserver binary, which is ctx.executable.devserver_host, in the runfiles. For non-RBE and for RBE with a linux host, ctx.executable.devserver & ctx.executable.devserver_host will be the same binary.
Defaults to precompiled go binary setup by @bazel/typescript npm package
devserver_host
Go based devserver executable for the host platform. Defaults to precompiled go binary setup by @bazel/typescript npm package
entry_module
The entry_module
should be the AMD module name of the entry module such as "__main__/src/index".
ts_devserver
concats the following snippet after the bundle to load the application:
require(["entry_module"]);
port
The port that the devserver will listen on.
scripts
User scripts to include in the JS bundle before the application sources
serving_path
The path you can request from the client HTML which serves the JavaScript bundle. If you don't specify one, the JavaScript can be loaded at /_/ts_scripts.js
static_files
Arbitrary files which to be served, such as index.html. They are served relative to the package where this rule is declared.
ts_library
ts_library
type-checks and compiles a set of TypeScript sources to JavaScript.
First read the Alternatives section above.
ts_project
is recommended for new uses.
The ts_library
rule invokes the TypeScript compiler on one compilation unit,
or "library" (generally one directory of source files).
It produces declarations files (.d.ts
) which are used for compiling downstream
TypeScript targets and JavaScript for the browser and Closure compiler.
To start, create a BUILD
file next to your sources:
package(default_visibility=["//visibility:public"])
load("//packages/typescript:index.bzl", "ts_library")
ts_library(
name = "my_code",
srcs = glob(["*.ts"]),
deps = ["//path/to/other:library"],
)
If your ts_library target has npm dependencies you can specify these
with fine grained npm dependency targets created by the yarn_install
or
npm_install
rules:
ts_library(
name = "my_code",
srcs = glob(["*.ts"]),
deps = [
"@npm//@types/node",
"@npm//@types/foo",
"@npm//foo",
"//path/to/other:library",
],
)
You can also use the @npm//@types
target which will include all
packages in the @types
scope as dependencies.
If you are using self-managed npm dependencies, you can use the
node_modules
attribute in ts_library
and point it to the
//:node_modules
filegroup defined in your root BUILD.bazel
file.
You'll also need to override the compiler
attribute if you do this
as the Bazel-managed deps and self-managed cannot be used together
in the same rule.
ts_library(
name = "my_code",
srcs = glob(["*.ts"]),
deps = ["//path/to/other:library"],
node_modules = "//:node_modules",
compiler = "//:@bazel/typescript/tsc_wrapped",
)
To build a ts_library
target run:
bazel build //path/to/package:target
The resulting .d.ts
file paths will be printed. Additionally, the .js
outputs from TypeScript will be written to disk, next to the .d.ts
files 1.
Note that the tsconfig.json
file used for compilation should be the same one
your editor references, to keep consistent settings for the TypeScript compiler.
By default, ts_library
uses the tsconfig.json
file in the workspace root
directory. See the notes about the tsconfig
attribute in the ts_library API docs.
1 The declarationDir compiler option will be silently overwritten if present.
Self-managed npm dependencies
We recommend you use Bazel managed dependencies, but if you would like
Bazel to also install a node_modules
in your workspace you can also
point the node_repositories
repository rule in your WORKSPACE
file to
your package.json
.
node_repositories(package_json = ["//:package.json"])
You can then run yarn
in your workspace with:
$ bazel run @nodejs//:yarn_node_repositories
To use your workspace node_modules
folder as a dependency in ts_library
and
other rules, add the following to your root BUILD.bazel
file:
filegroup(
name = "node_modules",
srcs = glob(
include = [
"node_modules/**/*.js",
"node_modules/**/*.d.ts",
"node_modules/**/*.json",
"node_modules/.bin/*",
],
exclude = [
# Files under test & docs may contain file names that
# are not legal Bazel labels (e.g.,
# node_modules/ecstatic/test/public/ä¸æ/æªæ¡.html)
"node_modules/**/test/**",
"node_modules/**/docs/**",
# Files with spaces in the name are not legal Bazel labels
"node_modules/**/* */**",
"node_modules/**/* *",
],
),
)
# Create a tsc_wrapped compiler rule to use in the ts_library
# compiler attribute when using self-managed dependencies
nodejs_binary(
name = "@bazel/typescript/tsc_wrapped",
entry_point = "@npm//:node_modules/@bazel/typescript/internal/tsc_wrapped/tsc_wrapped.js",
# Point bazel to your node_modules to find the entry point
node_modules = "//:node_modules",
)
See https://github.com/bazelbuild/rules_nodejs#dependencies for more information on managing npm dependencies with Bazel.
Customizing the TypeScript compiler binary
An example use case is needing to increase the NodeJS heap size used for compilations.
Similar to above, you declare your own binary for running tsc_wrapped
, e.g.:
nodejs_binary(
name = "tsc_wrapped_bin",
entry_point = "@npm//:node_modules/@bazel/typescript/internal/tsc_wrapped/tsc_wrapped.js",
templated_args = [
"--node_options=--max-old-space-size=2048",
],
data = [
"@npm//protobufjs",
"@npm//source-map-support",
"@npm//tsutils",
"@npm//typescript",
"@npm//@bazel/typescript",
],
)
then refer to that target in the compiler
attribute of your ts_library
rule.
Note that nodejs_binary
targets generated by npm_install
/yarn_install
can include data dependencies
on packages which aren't declared as dependencies. For example, if you use tsickle to generate Closure Compiler-compatible JS,
then it needs to be a data
dependency of tsc_wrapped
so that it can be loaded at runtime.
Accessing JavaScript outputs
The default output of the ts_library
rule is the .d.ts
files.
This is for a couple reasons:
- help ensure that downstream rules which access default outputs will not require a cascading re-build when only the implementation changes but not the types
- make you think about whether you want the
devmode
(named UMD) orprodmode
outputs
You can access the JS output by adding a filegroup
rule after the ts_library
,
for example
ts_library(
name = "compile",
srcs = ["thing.ts"],
)
filegroup(
name = "thing.js",
srcs = ["compile"],
# Change to es6_sources to get the 'prodmode' JS
output_group = "es5_sources",
)
my_rule(
name = "uses_js",
deps = ["thing.js"],
)
Serving TypeScript for development
There are two choices for development mode:
- Use the
ts_devserver
rule to bring up our simple, fast development server. This is intentionally very simple, to help you get started quickly. However, since there are many development servers available, we do not want to mirror their features in yet another server we maintain. - Teach your real frontend server to serve files from Bazel's output directory.
This is not yet documented. Choose this option if you have an existing server
used in development mode, or if your requirements exceed what the
ts_devserver
supports. Be careful that your development round-trip stays fast (should be under two seconds).
To use ts_devserver
, you simply load
the rule, and call it with deps
that
point to your ts_library
target(s):
load("//packages/typescript:index.bzl", "ts_devserver", "ts_library")
ts_library(
name = "app",
srcs = ["app.ts"],
)
ts_devserver(
name = "devserver",
# We'll collect all the devmode JS sources from these TypeScript libraries
deps = [":app"],
# This is the path we'll request from the browser, see index.html
serving_path = "/bundle.js",
# The devserver can serve our static files too
static_files = ["index.html"],
)
The index.html
should be the same one you use for production, and it should
load the JavaScript bundle from the path indicated in serving_path
.
If you don't have an index.html file, a simple one will be generated by the
ts_devserver
.
See examples/app
in this repository for a working example. To run the
devserver, we recommend you use ibazel:
$ ibazel run examples/app:devserver
ibazel
will keep the devserver program running, and provides a LiveReload
server so the browser refreshes the application automatically when each build
finishes.
Writing TypeScript code for ts_library
The custom TypeScript compiler tsc_wrapped
has your workspace path mapped, so you can import
from an absolute path starting from your workspace.
/WORKSPACE
:
workspace(name = "myworkspace")
/some/long/path/to/deeply/nested/subdirectory.ts
:
import {thing} from 'myworkspace/place';
will import from /place.ts
.
Since this is an extension to the vanilla TypeScript compiler, editors which use the TypeScript language services to provide code completion and inline type checking will not be able to resolve the modules. In the above example, adding
"paths": {
"myworkspace/*": ["*"]
}
to tsconfig.json
will fix the imports for the common case of using absolute paths.
See path mapping for more details on the paths syntax.
Similarly, you can use path mapping to teach the editor how to resolve imports
from ts_library
rules which set the module_name
attribute.
name
A unique name for this target.
angular_assets
Additional files the Angular compiler will need to read as inputs. Includes .css and .html files
compiler
Sets a different TypeScript compiler binary to use for this library.
For example, we use the vanilla TypeScript tsc.js for bootstrapping,
and Angular compilations can replace this with ngc
.
The default ts_library compiler depends on the //@bazel/typescript
target which is setup for projects that use bazel managed npm deps and
install the @bazel/typescript npm package.
data
deps
Compile-time dependencies, typically other ts_library targets
devmode_module
Set the typescript module
compiler option for devmode output.
This value will override the module
option in the user supplied tsconfig.
devmode_target
Set the typescript target
compiler option for devmode output.
This value will override the target
option in the user supplied tsconfig.
expected_diagnostics
generate_externs
internal_testing_type_check_dependencies
Testing only, whether to type check inputs that aren't srcs.
link_workspace_root
Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. If source files need to be required then they can be copied to the bin_dir with copy_to_bin.
module_name
module_root
node_modules
The npm packages which should be available during the compile.
The default value of //typescript:typescript__typings
is setup
for projects that use bazel managed npm deps. This default is in place
since ts_library will always depend on at least the typescript
default libs which are provided by //typescript:typescript__typings
.
This attribute is DEPRECATED. As of version 0.18.0 the recommended
approach to npm dependencies is to use fine grained npm dependencies
which are setup with the yarn_install
or npm_install
rules.
For example, in targets that used a //:node_modules
filegroup,
ts_library(
name = "my_lib",
...
node_modules = "//:node_modules",
)
which specifies all files within the //:node_modules
filegroup
to be inputs to the my_lib
. Using fine grained npm dependencies,
my_lib
is defined with only the npm dependencies that are
needed:
ts_library(
name = "my_lib",
...
deps = [
"@npm//@types/foo",
"@npm//@types/bar",
"@npm//foo",
"@npm//bar",
...
],
)
In this case, only the listed npm packages and their
transitive deps are includes as inputs to the my_lib
target
which reduces the time required to setup the runfiles for this
target (see https://github.com/bazelbuild/bazel/issues/5153).
The default typescript libs are also available via the node_modules
default in this case.
The @npm external repository and the fine grained npm package
targets are setup using the yarn_install
or npm_install
rule
in your WORKSPACE file:
yarn_install(
name = "npm",
package_json = "//:package.json",
yarn_lock = "//:yarn.lock",
)
prodmode_module
Set the typescript module
compiler option for prodmode output.
This value will override the module
option in the user supplied tsconfig.
prodmode_target
Set the typescript target
compiler option for prodmode output.
This value will override the target
option in the user supplied tsconfig.
runtime
runtime_deps
srcs
The TypeScript source files to compile.
supports_workers
Intended for internal use only.
Allows you to disable the Bazel Worker strategy for this library. Typically used together with the "compiler" setting when using a non-worker aware compiler binary.
tsconfig
A tsconfig.json file containing settings for TypeScript compilation.
Note that some properties in the tsconfig are governed by Bazel and will be
overridden, such as target
and module
.
The default value is set to //:tsconfig.json
by a macro.
To use the default, create a BUILD.bazel
file in your workspace root.
If your tsconfig.json
file is in the root, use
exports_files(["tsconfig.json"], visibility = ["//visibility:public"])
otherwise create an alias:
alias(
name = "tsconfig.json",
actual = "//path/to/my:tsconfig.json",
)
Or, instead of the default you can give an explicit tsconfig
attribute to all ts_library
targets.
tsickle_typed
If using tsickle, instruct it to translate types to ClosureJS format
use_angular_plugin
Run the Angular ngtsc compiler under ts_library
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:index.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).
Unlike ts_library
, this rule is the thinnest possible layer of Bazel interoperability on top
of the TypeScript compiler. It shifts the burden of configuring TypeScript into the tsconfig.json file.
See https://github.com/bazelbuild/rules_nodejs/blob/master/docs/TypeScript.md#alternatives
for more details about the trade-offs between the two rules.
Some TypeScript options affect which files are emitted, and Bazel wants to know these ahead-of-time. So several options from the tsconfig file must be mirrored as attributes to ts_project. See https://www.typescriptlang.org/v2/en/tsconfig for a listing of the TypeScript options.
Any code that works with tsc
should work with ts_project
with a few caveats:
- Bazel requires that the
outDir
(anddeclarationDir
) be set tobazel-out/[target architecture]/bin/path/to/package
so we override whatever settings appear in your tsconfig. - 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.
Note: in order for TypeScript to resolve relative references to the bazel-out folder, we recommend that the base tsconfig contain a rootDirs section that includes all possible locations they may appear.
We hope this will not be needed in some future release of TypeScript. Follow https://github.com/microsoft/TypeScript/issues/37257 for more info.
For example, if the base tsconfig file relative to the workspace root is
path/to/tsconfig.json
then you should configure like:"compilerOptions": { "rootDirs": [ ".", "../../bazel-out/darwin-fastbuild/bin/path/to", "../../bazel-out/k8-fastbuild/bin/path/to", "../../bazel-out/x64_windows-fastbuild/bin/path/to", "../../bazel-out/darwin-dbg/bin/path/to", "../../bazel-out/k8-dbg/bin/path/to", "../../bazel-out/x64_windows-dbg/bin/path/to", ] }
See some related discussion including both "rootDirs" and "paths" for a monorepo setup using custom import paths: https://github.com/bazelbuild/rules_nodejs/issues/2298
Issues when running non-sandboxed
When using a non-sandboxed spawn strategy (which is the default on Windows), you may observe these problems which require workarounds:
Bazel deletes outputs from the previous execution before running
tsc
. This causes a problem with TypeScript's incremental mode: if the.tsbuildinfo
file is not known to be an output of the rule, then Bazel will leave it in the output directory, and whentsc
runs, it may see that the outputs written by the prior invocation are up-to-date and skip the emit of these files. This will cause Bazel to intermittently fail with an error that some outputs were not written. This is why we depend oncomposite
and/orincremental
attributes to be provided, so we can tell Bazel to expect a.tsbuildinfo
output to ensure it is deleted before a subsequent compilation. At present, we don't do anything useful with the.tsbuildinfo
output, and this rule does not actually have incremental behavior. Deleting the file is actually counter-productive in terms of TypeScript compile performance. Follow https://github.com/bazelbuild/rules_nodejs/issues/1726When using Project References, TypeScript will expect to verify that the outputs of referenced projects are up-to-date with respect to their inputs. (This is true even without using the
--build
option). When using a non-sandboxed spawn strategy,tsc
can read the sources from otherts_project
rules in your project, and will expect that thetsconfig.json
file for those references will indicate where the outputs were written. However theoutDir
is determined by this Bazel rule so it cannot be known from reading thetsconfig.json
file. This problem is manifested as a TypeScript diagnostic likeerror TS6305: Output file '/path/to/execroot/a.d.ts' has not been built from source file '/path/to/execroot/a.ts'.
As a workaround, you can give the Windows "fastbuild" output directory as theoutDir
in your tsconfig file. On other platforms, the value isn't read so it does no harm. See https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/typescript/test/ts_project as an example. We hope this will be fixed in a future release of TypeScript; follow https://github.com/microsoft/TypeScript/issues/37378When TypeScript encounters an import statement, it adds the source file resolved by that reference to the program. However you may have included that source file in a different project, so this causes the problem mentioned above where a source file is in multiple programs. (Note, if you use Project References this is not the case, TS will know the referenced file is part of the other program.) This will result in duplicate emit for the same file, which produces an error since the files written to the output tree are read-only. Workarounds include using using Project References, or simply grouping the whole compilation into one program (if this doesn't exceed your time budget).
name
A name for the target.
We recommend you use the basename (no .json
extension) of the tsconfig file that should be compiled.
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
provdes TsConfigInfo
such as ts_config
.
By default, we assume the tsconfig file is named by adding .json
to the name
attribute.
EXPERIMENTAL: generated tsconfig
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:
ts_project(
tsconfig = {
"compilerOptions": {
"declaration": True,
},
},
)
and
ts_project(
declaration = True,
)
srcs
List of labels of TypeScript source files to be provided to the compiler.
If absent, defaults to **/*.ts[x]
(all TypeScript files in the package).
args
List of strings of additional command-line arguments to pass to tsc.
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
.
DEPRECATED, to be removed in 3.0:
For backwards compatibility, this accepts a list of Labels of the "chained"
tsconfig files. You should instead use a single Label of a ts_config
target.
Follow this deprecation: https://github.com/bazelbuild/rules_nodejs/issues/2140
allow_js
boolean; Specifies whether TypeScript will read .js and .jsx files. When used with declaration, TypeScript will generate .d.ts files from .js files.
declaration
if the declaration
bit is set in the tsconfig.
Instructs Bazel to expect a .d.ts
output for each .ts
source.
source_map
if the sourceMap
bit is set in the tsconfig.
Instructs Bazel to expect a .js.map
output for each .ts
source.
declaration_map
if the declarationMap
bit is set in the tsconfig.
Instructs Bazel to expect a .d.ts.map
output for each .ts
source.
composite
if 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
if the incremental
bit is set in the tsconfig.
Instructs Bazel to expect a .tsbuildinfo
output.
emit_declaration_only
if the emitDeclarationOnly
bit is set in the tsconfig.
Instructs Bazel not to expect .js
or .js.map
outputs for .ts
sources.
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.
For example, tsc = "@my_deps//typescript/bin:tsc"
Or you can pass a custom compiler binary instead.
worker_tsc_bin
Label of the TypeScript compiler binary to run when running in worker mode.
For example, tsc = "@my_deps//node_modules/typescript/bin/tsc"
Or you can pass a custom compiler binary instead.
worker_typescript_module
Label of the package containing all data deps of worker_tsc_bin.
For example, tsc = "@my_deps//typescript"
validate
boolean; whether to check that the tsconfig settings match the attributes.
supports_workers
Experimental! Use only with caution.
Allows you to enable the Bazel Persistent Workers strategy for this project. See https://docs.bazel.build/versions/master/persistent-workers.html
This requires that the tsc binary support a --watch
option.
NOTE: this does not work on Windows yet. We will silently fallback to non-worker mode on Windows regardless of the value of this attribute. Follow https://github.com/bazelbuild/rules_nodejs/issues/2277 for progress on this feature.
declaration_dir
a 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
a 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
a 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.
link_workspace_root
Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. If source files need to be required then they can be copied to the bin_dir with copy_to_bin.
kwargs
passed through to underlying rule, allows eg. visibility, tags