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

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.

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

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

Rules

`nodejs_library`

Creates a reusable Node.js library.

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.

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.

load("@rbs//nodejs/rules.rbs", "nodejs_test")

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

Example: Express API

WORKSPACE.rbs
BUILD.rbs
Commands

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

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"},
)

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

​Node.js SDK

​Setup

​Toolchain

​Dependencies

​Rules

​nodejs_library

​nodejs_binary

​nodejs_test

​Example: Express API

Node.js SDK

Setup

Toolchain

Dependencies

Rules

`nodejs_library`

`nodejs_binary`

`nodejs_test`

Example: Express API