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

# TypeScript SDK

> Build TypeScript applications with RBS — automatic compilation, custom tsconfig options, and seamless integration with Node.js rules.

# TypeScript SDK

RBS supports TypeScript through the Node.js SDK with automatic `tsc` compilation. All `.ts` files are compiled to `.js` transparently using configurable compiler options.

## Setup

Use the same Node.js toolchain setup. TypeScript support is built into the `nodejs_binary` and `nodejs_library` rules.

```python filename="WORKSPACE.rbs" theme={null}
load("@rbs//nodejs/toolchain.rbs", "nodejs_toolchain")
load("@rbs//nodejs/dependencies.rbs", "nodejs_repository")

nodejs_toolchain(name = "nodejs", version = "20.11.0")

# TypeScript compiler (auto-managed)
nodejs_repository(name = "typescript_repo", package = "typescript", version = "5.3.3")

# Type definitions
nodejs_repository(name = "types_node_repo", package = "@types/node", version = "20.11.5")
nodejs_repository(name = "types_express_repo", package = "@types/express", version = "4.17.21")

# Application dependencies
nodejs_repository(name = "express_repo", package = "express", version = "4.18.2")
```

## TypeScript Compilation

Add `ts_compiler_options` to any `nodejs_binary` or `nodejs_library` to enable TypeScript compilation:

```python theme={null}
nodejs_library(
    name = "utils",
    srcs = ["src/utils/math.ts", "src/utils/string.ts"],
    deps = [":lodash_repo", ":types_lodash_repo"],
    ts_compiler_options = {
        "target": "ES2020",
        "strict": True,
        "declaration": True,
    },
)
```

### Common Compiler Options

| Option            | Type   | Description                                       |
| ----------------- | ------ | ------------------------------------------------- |
| `target`          | string | ECMAScript target (`"ES2020"`, `"ES2022"`, etc.). |
| `module`          | string | Module system (`"commonjs"`, `"esnext"`, etc.).   |
| `strict`          | bool   | Enable strict type checking.                      |
| `declaration`     | bool   | Generate `.d.ts` declaration files.               |
| `esModuleInterop` | bool   | Enable interop between CommonJS and ES modules.   |
| `skipLibCheck`    | bool   | Skip type checking of declaration files.          |

## Rules

All Node.js rules support TypeScript when `ts_compiler_options` is provided.

### `nodejs_library` (TypeScript)

```python theme={null}
load("@rbs//nodejs/rules.rbs", "nodejs_library")

nodejs_library(
    name = "models",
    srcs = ["src/models/user.ts", "src/models/product.ts"],
    ts_compiler_options = {"target": "ES2020", "strict": True},
)

nodejs_library(
    name = "routes",
    srcs = ["src/routes/api.ts"],
    deps = [":models", ":utils", ":express_repo", ":types_express_repo"],
    ts_compiler_options = {"target": "ES2020", "strict": True},
)
```

### `nodejs_binary` (TypeScript)

```python theme={null}
load("@rbs//nodejs/rules.rbs", "nodejs_binary")

nodejs_binary(
    name = "server",
    srcs = ["src/server.ts"],
    main = "src/server.ts",
    deps = [
        ":routes", ":utils", ":models",
        ":express_repo", ":types_express_repo", ":types_node_repo",
        ":typescript_repo",
    ],
    env = {"NODE_ENV": "development", "PORT": "4000"},
    ts_compiler_options = {
        "target": "ES2020",
        "module": "commonjs",
        "strict": True,
        "esModuleInterop": True,
    },
)
```

### Linting

Lint TypeScript files with Prettier:

```python theme={null}
load("@rbs//nodejs/lint.rbs", "nodejs_lint")

nodejs_lint(
    name = "lint",
    srcs = glob(["src/**/*.ts"], exclude = ["node_modules/**", "dist/**"]),
    linters = ["prettier"],
)
```

## Example: TypeScript Express Server with Containers

<Tabs>
  <Tab title="BUILD.rbs">
    ```python theme={null}
    load("@rbs//nodejs/rules.rbs", "nodejs_binary", "nodejs_library")
    load("@rbs//oci/rules.rbs", "oci_image")
    load("@rbs//nodejs/lint.rbs", "nodejs_lint")

    nodejs_library(
        name = "utils",
        srcs = ["src/utils/math.ts", "src/utils/string.ts"],
        deps = [":lodash_repo", ":types_lodash_repo"],
        ts_compiler_options = {"target": "ES2020", "strict": True, "declaration": True},
    )

    nodejs_binary(
        name = "server",
        srcs = ["src/server.ts"],
        main = "src/server.ts",
        deps = [":utils", ":express_repo", ":types_express_repo", ":types_node_repo", ":typescript_repo"],
        env = {"NODE_ENV": "development", "PORT": "4000"},
        ts_compiler_options = {"target": "ES2020", "module": "commonjs", "strict": True, "esModuleInterop": True},
    )

    oci_image(
        name = "server_image",
        binary = ":server",
        base = "ubuntu:22.04",
        env = {"NODE_ENV": "production", "PORT": "8080"},
        ports = ["8080/tcp"],
        tag = "ts-server:latest",
    )

    nodejs_lint(
        name = "lint",
        srcs = glob(["src/**/*.ts"]),
        linters = ["prettier"],
    )
    ```
  </Tab>

  <Tab title="Commands">
    ```bash theme={null}
    rbs build server             # Compile TypeScript and build
    rbs run server               # Start the server
    rbs build server_image       # Build container image
    rbs build lint               # Run Prettier
    ```
  </Tab>
</Tabs>