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
Register a Node.js toolchain in WORKSPACE.rbs:
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
