> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript with Bazel

> Bazel TypeScript guide for rules_ts: configure ts_project, swap the transpiler for swc or esbuild, share tsconfig.json, and integrate with rules_js.

[TypeScript](https://www.typescriptlang.org/) works great with Bazel.
The `ts_project` rule handles type-checking and transpilation, and integrates with your existing `tsconfig.json`.

**API reference:**
[TypeScript rules](/bazel/javascript/aspect_rules_ts/ts_defs)

### Configuration

You can use a single `tsconfig.json` for the whole repository or one per package.
You must mirror some `tsconfig.json` values into your `BUILD` file—if they don't match, `rules_ts` prints an error with the exact command to fix it.

For more info, see [Configuring TypeScript](https://github.com/aspect-build/rules_ts/blob/main/docs/tsconfig.md).

### Transpiler

TypeScript transpilation is separate from type-checking, so you can swap in a faster tool like [swc](https://swc.rs/) or [esbuild](https://esbuild.github.io/) instead of the default `tsc`.
On the first run, `rules_ts` suggests `.bazelrc` settings for your chosen transpiler.

See the [Transpiling TypeScript into JavaScript](https://github.com/aspect-build/rules_ts/blob/main/docs/transpiler.md).

### Isolated declarations

For large monorepos, you can go further by enabling TypeScript's `isolatedDeclarations` option.
This makes declaration file (`.d.ts`) generation a single-file transform with no dependencies, so Bazel can run all type-check actions fully in parallel rather than sequentially along the dependency chain.

See [Isolated Declarations](/docs/bazel/javascript/isolated-declarations).

**API reference:**
[TypeScript definitions](/bazel/javascript/aspect_rules_ts/ts_defs) |
[ts extensions](/bazel/javascript/aspect_rules_ts/ts_extensions)

**Troubleshooting:**
[rules\_ts troubleshooting](https://github.com/aspect-build/rules_ts/blob/main/docs/troubleshooting.md) |
[Performance tips](https://github.com/aspect-build/rules_ts/blob/main/docs/performance.md)

<Note>
  Bazel requires that you explicitly declare **all** dependencies, including `@types/node`. This differs from TypeScript's ambient imports where any types in `node_modules` are automatically available.
</Note>

### Wrapping ts\_project in a macro

Many organizations set default values for `ts_project`—such as shared `tsconfig` settings or a standard transpiler—so it's common to write a macro that wraps `ts_project` and have developers load that instead of using `@aspect_rules_ts` directly.

See the [Macros](/docs/bazel/javascript/rules_js#macros) section of the `rules_js` documentation for an example of this pattern.

### Examples

The [rules\_ts examples folder](https://github.com/aspect-build/rules_ts/tree/main/examples) has a range of starting points, and the [bazel-examples repository](https://github.com/aspect-build/bazel-examples) includes larger real-world setups for [Jest](https://github.com/aspect-build/bazel-examples/tree/main/jest) and [Angular](https://github.com/aspect-build/bazel-examples/tree/main/angular). For React, see the [bazel-build/react example](https://github.com/bazelbuild/examples/tree/main/frontend/react).

If you'd like to add an example, fund a [Feature Request](https://github.com/aspect-build/rules_ts/issues/new/choose).

## Telemetry

`rules_js` collects limited usage data through
[`tools_telemetry`](https://github.com/aspect-build/tools_telemetry), reported to Aspect Build, Inc. and governed by the [Aspect Privacy Policy](https://www.aspect.build/privacy-policy).