@bazel/typescript/README.md

TypeScript rules for Bazel

# TypeScript rules for Bazel

The TypeScript rules integrate the TypeScript compiler with Bazel.


## Alternatives

This package provides Bazel wrappers around the TypeScript compiler.

At a high level, there are three alternatives provided: `tsc`, `ts_project`, `ts_library`.
This section describes the trade-offs between these rules.

`tsc` is the raw TypeScript compiler published by the team at Microsoft.
Like any npm package that exposes a binary, rules_nodejs will generate an `index.bzl` file allowing
you to run `tsc`.

To use it, add the load statement `load("@npm//typescript:index.bzl", "tsc")` to your BUILD file.
Then call it, using the [`npm_package_bin`](Built-ins#npm_package_bin) documentation.

The only reason to use raw `tsc` is if you want to compile an opaque directory of `.ts` files and cannot enumerate them to Bazel.
(For example if the `.ts` files are generated by some tool).
This will produce an opaque directory of `.js` file outputs, which you won't be able to individually reference.
Any other use case for `tsc` is better served by using `ts_project`.

`ts_project` simply runs `tsc --project`, with Bazel knowing which outputs to expect based on the TypeScript compiler options, and with interoperability with other TypeScript rules via a Bazel Provider (DeclarationInfo) that transmits the type information.
It is intended as an easy on-boarding for existing TypeScript code and should be familiar if your background is in frontend ecosystem idioms.
Any behavior of `ts_project` should be reproducible outside of Bazel, with a couple of caveats noted in the rule documentation below.

`ts_library` is an open-sourced version of the rule used to compile TS code at Google.
It should be familiar if your background is in Bazel idioms.
It is very complex, involving code generation of the `tsconfig.json` file, a custom compiler binary, and a lot of extra features.
It is also opinionated, and may not work with existing TypeScript code. For example:

- Your TS code must compile under the `--declaration` flag so that downstream libraries depend only on types, not implementation. This makes Bazel faster by avoiding cascading rebuilds in cases where the types aren't changed.
- We control the output format and module syntax so that downstream rules can rely on them.

On the other hand, `ts_library` is also fast and optimized.
We keep a running TypeScript compile running as a daemon, using Bazel workers.
This process avoids re-parse and re-JIT of the >1MB `typescript.js` and keeps cached bound ASTs for input files which saves time.
We also produce JS code which can be loaded faster (using named AMD module format) and which can be consumed by the Closure Compiler (via integration with [tsickle](https://github.com/angular/tsickle)).


## Installation

Add a `devDependency` on `@bazel/typescript`

```sh
$ yarn add -D @bazel/typescript
# or
$ npm install --save-dev @bazel/typescript
```

Watch for any `peerDependency` warnings - we assume you have already installed the `typescript` package from npm.

Create a `BUILD.bazel` file in your workspace root. If your `tsconfig.json` file is in the root, use

```python
exports_files(["tsconfig.json"], visibility = ["//visibility:public"])
```

otherwise create an alias:

```python
alias(
    name = "tsconfig.json",
    actual = "//path/to/my:tsconfig.json",
)
```

Make sure to remove the `--noEmit` compiler option from your `tsconfig.json`. This is not compatible with the `ts_library` rule.


## User-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`.

```python
node_repositories(package_json = ["//:package.json"])
```

You can then run `yarn` in your workspace with:

```sh
$ 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:

```python
js_library(
    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/**/* *",
        ],
    ),
    # Provide ExternalNpmPackageInfo which is used by downstream rules
    # that use these npm dependencies
    external_npm_package = True,
)

# Create a tsc_wrapped compiler rule to use in the ts_library
# compiler attribute when using user-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
    data = ["//:node_modules"],
)
```

See the [dependencies docs](dependencies.html) 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.:

```python
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](https://github.com/angular/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.


## Usage


### Compiling TypeScript: `ts_library`

The `ts_library` rule invokes the TypeScript compiler on one compilation unit,
or "library" (generally one directory of source files).

Create a `BUILD` file next to your sources:

```python
package(default_visibility=["//visibility:public"])
load("//@bazel/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:

```python
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 user-managed npm dependencies, you can pass your `//:node_modules`
target defined in your root `BUILD.bazel` file to the deps of `ts_library`.
You'll also need to override the `compiler` attribute if you do this
as the Bazel-managed deps and user-managed cannot be used together
in the same rule.

```python
ts_library(
    name = "my_code",
    srcs = glob(["*.ts"]),
    deps = [
        "//path/to/other:library",
        "//: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 <sup>1</sup>.

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

> <sup>1</sup> The
> [declarationDir](https://www.typescriptlang.org/docs/handbook/compiler-options.html)
> compiler option will be silently overwritten if present.

[ts_library API docs]: http://tsetse.info/api/build_defs.html#ts_library


## 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`) or `prodmode` outputs

You can access the JS output by adding a `filegroup` rule after the `ts_library`,
for example

```python
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

This is now documented in the `@bazel/concatjs` package.


## Writing TypeScript code for Bazel

Bazel's TypeScript compiler has your workspace path mapped, so you can import
from an absolute path starting from your workspace.

`/WORKSPACE`:
```python
workspace(name = "myworkspace")
```

`/some/long/path/to/deeply/nested/subdirectory.ts`:
```javascript
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
```json
"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.


### Notes

If you'd like a "watch mode", try [ibazel].

At some point, we plan to release a tool similar to [gazelle] to generate the
`BUILD` files from your source code.

[gazelle]: https://github.com/bazelbuild/bazel-gazelle
[ibazel]: https://github.com/bazelbuild/bazel-watcher
[path mapping]: https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping


## ts_config

**USAGE**

<pre>
ts_config(<a href="#ts_config-name">name</a>, <a href="#ts_config-deps">deps</a>, <a href="#ts_config-src">src</a>)
</pre>

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


<h4 id="ts_config-name">name</h4>

(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.


<h4 id="ts_config-deps">deps</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Additional tsconfig.json files referenced via extends

Defaults to `[]`

<h4 id="ts_config-src">src</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory*): The tsconfig.json file passed to the TypeScript compiler




## ts_library

**USAGE**

<pre>
ts_library(<a href="#ts_library-name">name</a>, <a href="#ts_library-angular_assets">angular_assets</a>, <a href="#ts_library-compiler">compiler</a>, <a href="#ts_library-data">data</a>, <a href="#ts_library-deps">deps</a>, <a href="#ts_library-devmode_module">devmode_module</a>, <a href="#ts_library-devmode_target">devmode_target</a>,
           <a href="#ts_library-expected_diagnostics">expected_diagnostics</a>, <a href="#ts_library-generate_externs">generate_externs</a>, <a href="#ts_library-internal_testing_type_check_dependencies">internal_testing_type_check_dependencies</a>,
           <a href="#ts_library-link_workspace_root">link_workspace_root</a>, <a href="#ts_library-module_name">module_name</a>, <a href="#ts_library-module_root">module_root</a>, <a href="#ts_library-prodmode_module">prodmode_module</a>, <a href="#ts_library-prodmode_target">prodmode_target</a>, <a href="#ts_library-runtime">runtime</a>,
           <a href="#ts_library-runtime_deps">runtime_deps</a>, <a href="#ts_library-srcs">srcs</a>, <a href="#ts_library-supports_workers">supports_workers</a>, <a href="#ts_library-tsconfig">tsconfig</a>, <a href="#ts_library-tsickle_typed">tsickle_typed</a>, <a href="#ts_library-use_angular_plugin">use_angular_plugin</a>)
</pre>

`ts_library` type-checks and compiles a set of TypeScript sources to JavaScript.

It produces declarations files (`.d.ts`) which are used for compiling downstream
TypeScript targets and JavaScript for the browser and Closure compiler.


**ATTRIBUTES**


<h4 id="ts_library-name">name</h4>

(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.


<h4 id="ts_library-angular_assets">angular_assets</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Additional files the Angular compiler will need to read as inputs.
            Includes .css and .html files

Defaults to `[]`

<h4 id="ts_library-compiler">compiler</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): 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.

Defaults to `//@bazel/typescript/bin:tsc_wrapped`

<h4 id="ts_library-data">data</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*)

Defaults to `[]`

<h4 id="ts_library-deps">deps</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Compile-time dependencies, typically other ts_library targets

Defaults to `[]`

<h4 id="ts_library-devmode_module">devmode_module</h4>

(*String*): Set the typescript `module` compiler option for devmode output.

This value will override the `module` option in the user supplied tsconfig.

Defaults to `"umd"`

<h4 id="ts_library-devmode_target">devmode_target</h4>

(*String*): Set the typescript `target` compiler option for devmode output.

This value will override the `target` option in the user supplied tsconfig.

Defaults to `"es2015"`

<h4 id="ts_library-expected_diagnostics">expected_diagnostics</h4>

(*List of strings*)

Defaults to `[]`

<h4 id="ts_library-generate_externs">generate_externs</h4>

(*Boolean*)

Defaults to `True`

<h4 id="ts_library-internal_testing_type_check_dependencies">internal_testing_type_check_dependencies</h4>

(*Boolean*): Testing only, whether to type check inputs that aren't srcs.

Defaults to `False`

<h4 id="ts_library-link_workspace_root">link_workspace_root</h4>

(*Boolean*): 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.

Defaults to `False`

<h4 id="ts_library-module_name">module_name</h4>

(*String*)

Defaults to `""`

<h4 id="ts_library-module_root">module_root</h4>

(*String*)

Defaults to `""`

<h4 id="ts_library-prodmode_module">prodmode_module</h4>

(*String*): Set the typescript `module` compiler option for prodmode output.

This value will override the `module` option in the user supplied tsconfig.

Defaults to `"esnext"`

<h4 id="ts_library-prodmode_target">prodmode_target</h4>

(*String*): Set the typescript `target` compiler option for prodmode output.

This value will override the `target` option in the user supplied tsconfig.

Defaults to `"es2015"`

<h4 id="ts_library-runtime">runtime</h4>

(*String*)

Defaults to `"browser"`

<h4 id="ts_library-runtime_deps">runtime_deps</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*)  The dependencies of this attribute must provide: JsInfo


Defaults to `[]`

<h4 id="ts_library-srcs">srcs</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>, mandatory*): The TypeScript source files to compile.


<h4 id="ts_library-supports_workers">supports_workers</h4>

(*Boolean*): 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.

Defaults to `True`

<h4 id="ts_library-tsconfig">tsconfig</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): 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. This means you must
either:

- Have your `tsconfig.json` file in the workspace root directory
- Use an alias in the root BUILD.bazel file to point to the location of tsconfig:
    `alias(name="tsconfig.json", actual="//path/to:tsconfig-something.json")`
- Give an explicit `tsconfig` attribute to all `ts_library` targets

Defaults to `None`

<h4 id="ts_library-tsickle_typed">tsickle_typed</h4>

(*Boolean*): If using tsickle, instruct it to translate types to ClosureJS format

Defaults to `True`

<h4 id="ts_library-use_angular_plugin">use_angular_plugin</h4>

(*Boolean*): Run the Angular ngtsc compiler under ts_library

Defaults to `False`



## ts_project

**USAGE**

<pre>
ts_project(<a href="#ts_project-name">name</a>, <a href="#ts_project-tsconfig">tsconfig</a>, <a href="#ts_project-srcs">srcs</a>, <a href="#ts_project-args">args</a>, <a href="#ts_project-deps">deps</a>, <a href="#ts_project-extends">extends</a>, <a href="#ts_project-allow_js">allow_js</a>, <a href="#ts_project-declaration">declaration</a>, <a href="#ts_project-source_map">source_map</a>,
           <a href="#ts_project-declaration_map">declaration_map</a>, <a href="#ts_project-composite">composite</a>, <a href="#ts_project-incremental">incremental</a>, <a href="#ts_project-emit_declaration_only">emit_declaration_only</a>, <a href="#ts_project-ts_build_info_file">ts_build_info_file</a>, <a href="#ts_project-tsc">tsc</a>,
           <a href="#ts_project-typescript_package">typescript_package</a>, <a href="#ts_project-typescript_require_path">typescript_require_path</a>, <a href="#ts_project-validate">validate</a>, <a href="#ts_project-supports_workers">supports_workers</a>, <a href="#ts_project-declaration_dir">declaration_dir</a>,
           <a href="#ts_project-out_dir">out_dir</a>, <a href="#ts_project-root_dir">root_dir</a>, <a href="#ts_project-link_workspace_root">link_workspace_root</a>, <a href="#ts_project-kwargs">kwargs</a>)
</pre>

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` (and `declarationDir`) be set to
  `bazel-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/host/bin/path/to",
>         "../../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:

1) 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 when `tsc` 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 on `composite` and/or `incremental` 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/1726

2) When 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 other `ts_project`
   rules in your project, and will expect that the `tsconfig.json` file for those references will
   indicate where the outputs were written. However the `outDir` is determined by this Bazel rule so
   it cannot be known from reading the `tsconfig.json` file.
   This problem is manifested as a TypeScript diagnostic like
   `error 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 the `outDir` 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/37378

3) When 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).


**PARAMETERS**


<h4 id="ts_project-name">name</h4>

A name for the target.

We recommend you use the basename (no `.json` extension) of the tsconfig file that should be compiled.

Defaults to `"tsconfig"`

<h4 id="ts_project-tsconfig">tsconfig</h4>

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 generated `tsconfig.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,
)
```

Defaults to `None`

<h4 id="ts_project-srcs">srcs</h4>

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

Defaults to `None`

<h4 id="ts_project-args">args</h4>

List of strings of additional command-line arguments to pass to tsc.

Defaults to `[]`

<h4 id="ts_project-deps">deps</h4>

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

Defaults to `[]`

<h4 id="ts_project-extends">extends</h4>

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

Defaults to `None`

<h4 id="ts_project-allow_js">allow_js</h4>

boolean; Specifies whether TypeScript will read .js and .jsx files. When used with declaration,
TypeScript will generate .d.ts files from .js files.

Defaults to `False`

<h4 id="ts_project-declaration">declaration</h4>

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

Defaults to `False`

<h4 id="ts_project-source_map">source_map</h4>

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

Defaults to `False`

<h4 id="ts_project-declaration_map">declaration_map</h4>

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

Defaults to `False`

<h4 id="ts_project-composite">composite</h4>

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.

Defaults to `False`

<h4 id="ts_project-incremental">incremental</h4>

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

Defaults to `False`

<h4 id="ts_project-emit_declaration_only">emit_declaration_only</h4>

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

Defaults to `False`

<h4 id="ts_project-ts_build_info_file">ts_build_info_file</h4>

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

Defaults to `None`

<h4 id="ts_project-tsc">tsc</h4>

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.

Defaults to `None`

<h4 id="ts_project-typescript_package">typescript_package</h4>

Label of the package containing all data deps of tsc.

For example, `typescript_package = "@my_deps//typescript"`

Defaults to `"@npm//typescript"`

<h4 id="ts_project-typescript_require_path">typescript_require_path</h4>

Module name which resolves to typescript_package when required

For example, `typescript_require_path = "typescript"`

Defaults to `"typescript"`

<h4 id="ts_project-validate">validate</h4>

boolean; whether to check that the tsconfig settings match the attributes.

Defaults to `True`

<h4 id="ts_project-supports_workers">supports_workers</h4>

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.

Defaults to `False`

<h4 id="ts_project-declaration_dir">declaration_dir</h4>

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.

Defaults to `None`

<h4 id="ts_project-out_dir">out_dir</h4>

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.

Defaults to `None`

<h4 id="ts_project-root_dir">root_dir</h4>

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.

Defaults to `None`

<h4 id="ts_project-link_workspace_root">link_workspace_root</h4>

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.

Defaults to `False`

<h4 id="ts_project-kwargs">kwargs</h4>

passed through to underlying rule, allows eg. visibility, tags