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

# Node.js SDK

> Build and run Node.js applications with RBS — hermetic Node.js runtime, automatic npm package resolution, and zero npm CLI usage.

# Node.js SDK

RBS provides hermetic Node.js support with automatic runtime management, npm-compatible package resolution, and zero reliance on the `npm` or `yarn` CLI. RBS fetches and caches all packages directly.

## Setup

### Toolchain

Register a Node.js toolchain in `WORKSPACE.rbs`:

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

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

### Dependencies

Define npm packages using `nodejs_repository`. RBS resolves semver ranges and downloads all transitive dependencies.

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

nodejs_repository(name = "express_repo", package = "express", version = "4.18.2")
nodejs_repository(name = "cors_repo", package = "cors", version = "2.8.5")
nodejs_repository(name = "helmet_repo", package = "helmet", version = "7.1.0")
nodejs_repository(name = "morgan_repo", package = "morgan", version = "1.10.0")
nodejs_repository(name = "lodash_repo", package = "lodash", version = "4.17.21")
```

<Info>
  RBS manages npm packages directly — no `npm`, `yarn`, or `pnpm` CLI is ever invoked. All packages are hermetically cached in `.rbs/external-deps/`.
</Info>

## Rules

### `nodejs_library`

Creates a reusable Node.js library.

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

nodejs_library(
    name = "utils",
    srcs = ["lib/utils.js", "lib/logger.js"],
    deps = [":lodash_repo", ":uuid_repo"],
)

nodejs_library(
    name = "routes",
    srcs = ["lib/routes.js", "lib/middleware.js"],
    deps = [":utils", ":express_repo"],
)
```

| Attribute | Type   | Description                                        |
| --------- | ------ | -------------------------------------------------- |
| `name`    | string | Unique target name (required).                     |
| `srcs`    | list   | JavaScript source files.                           |
| `deps`    | list   | Dependencies (local targets or external packages). |

### `nodejs_binary`

Creates an executable Node.js application.

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

# Development server
nodejs_binary(
    name = "dev_server",
    srcs = ["server.js"],
    main = "server.js",
    deps = [":routes", ":utils", ":express_repo", ":cors_repo", ":morgan_repo"],
    env = {"NODE_ENV": "development", "PORT": "3000"},
)

# Production server
nodejs_binary(
    name = "prod_server",
    srcs = ["server.js"],
    main = "server.js",
    deps = [":routes", ":utils", ":express_repo", ":cors_repo", ":helmet_repo", ":morgan_repo"],
    env = {"NODE_ENV": "production", "PORT": "8080"},
)
```

| Attribute | Type   | Description                    |
| --------- | ------ | ------------------------------ |
| `name`    | string | Unique target name (required). |
| `srcs`    | list   | JavaScript source files.       |
| `main`    | string | Entry point file (required).   |
| `deps`    | list   | Dependencies.                  |
| `env`     | dict   | Environment variables.         |

### `nodejs_test`

Runs Node.js tests.

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

nodejs_test(
    name = "routes_test",
    srcs = ["tests/routes.test.js"],
    deps = [":routes", ":express_repo"],
)
```

## Example: Express API

<Tabs>
  <Tab title="WORKSPACE.rbs">
    ```python theme={null}
    load("@rbs//nodejs/toolchain.rbs", "nodejs_toolchain")
    load("@rbs//nodejs/dependencies.rbs", "nodejs_repository")

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

    nodejs_repository(name = "express_repo", package = "express", version = "4.18.2")
    nodejs_repository(name = "cors_repo", package = "cors", version = "2.8.5")
    nodejs_repository(name = "helmet_repo", package = "helmet", version = "7.1.0")
    nodejs_repository(name = "morgan_repo", package = "morgan", version = "1.10.0")
    nodejs_repository(name = "lodash_repo", package = "lodash", version = "4.17.21")
    nodejs_repository(name = "uuid_repo", package = "uuid", version = "9.0.1")
    ```
  </Tab>

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

    nodejs_library(
        name = "utils",
        srcs = ["lib/utils.js", "lib/logger.js"],
        deps = [":lodash_repo", ":uuid_repo"],
    )

    nodejs_library(
        name = "routes",
        srcs = ["lib/routes.js", "lib/middleware.js"],
        deps = [":utils", ":express_repo"],
    )

    nodejs_binary(
        name = "dev_server",
        srcs = ["server.js"],
        main = "server.js",
        deps = [":routes", ":utils", ":express_repo", ":cors_repo", ":morgan_repo"],
        env = {"NODE_ENV": "development", "PORT": "3000"},
    )

    nodejs_binary(
        name = "prod_server",
        srcs = ["server.js"],
        main = "server.js",
        deps = [":routes", ":utils", ":express_repo", ":cors_repo", ":helmet_repo", ":morgan_repo"],
        env = {"NODE_ENV": "production", "PORT": "8080"},
    )
    ```
  </Tab>

  <Tab title="Commands">
    ```bash theme={null}
    rbs build dev_server         # Build development server
    rbs run dev_server           # Start dev server on port 3000
    rbs build prod_server        # Build production server
    rbs run prod_server          # Start prod server on port 8080
    ```
  </Tab>
</Tabs>