JavaScript and TypeScript rules for Bazel

⚠️ Looking for new maintainers

Rules

• js_library
• web_bundle
• js_binary
• ts_library
• js_script
• js_test
• npm_packages
• npm_binary

Overview

If you're not already familiar with Bazel, install it first.

These rules allow you to set up a clean, modular and reusable build infrastructure for your JavaScript and TypeScript code.

Read through an introduction here.

Installation

First, install Bazel and Yarn.

Next, create a WORKSPACE file in your project root containing:

load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")

# Required for access to js_library, ts_library, js_test, web_bundle, etc.
git_repository(
  name = "bazel_javascript",
  remote = "https://github.com/zenclabs/bazel-javascript.git",
  tag = "0.0.28",
)

# Required for underlying dependencies such as Node and Yarn.
git_repository(
    name = "build_bazel_rules_nodejs",
    remote = "https://github.com/bazelbuild/rules_nodejs.git",
    tag = "0.15.0",
)

load("@build_bazel_rules_nodejs//:package.bzl", "rules_nodejs_dependencies")
rules_nodejs_dependencies()

load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories")

# By default, the Node and Yarn versions you have installed locally will be
# ignored, and Bazel will install a separate version instead. This helps
# achieve consistency across teams.
#
# See https://github.com/bazelbuild/rules_nodejs if you'd like to use your
# local Node and Yarn binaries instead.
node_repositories(package_json = [])

Basic example

Suppose you have the following directory structure:

[workspace]/
  WORKSPACE
  BUILD.bazel
  package.json
  yarn.lock
  src/
    BUILD.bazel
    main.js
    util/
      BUILD.bazel
      constants.js

package.json

{
  "dependencies": {
    "textbuilder": "^1.0.3"
  }
}

BUILD.bazel

package(default_visibility = ["//visibility:public"])

load("@bazel_javascript//:defs.bzl", "js_binary", "npm_packages")

js_binary(
  name = "app",
  lib = "//src:main",
  entry = "main.js",
)

npm_packages(
  name = "packages",
  package_json = ":package.json",
  yarn_lock = ":yarn.lock",
)

src/main.js

import { GREETING } from "./util/constants";

console.log(GREETING);

src/BUILD.bazel

package(default_visibility = ["//visibility:public"])

load("@bazel_javascript//:defs.bzl", "js_library")

js_library(
  name = "main",
  srcs = [
    "main.js",
  ],
  deps = [
    "//src/util:constants",
  ],
)

src/util/constants.js

import TextBuilder from "textbuilder";

const t = new TextBuilder();
t.append("Hello ", process.argv[2] || "Daniel");
export const GREETING = t.build();

src/util/BUILD.bazel

package(default_visibility = ["//visibility:public"])

load("@bazel_javascript//:defs.bzl", "js_library")

js_library(
  name = "constants",
  srcs = [
    "constants.js",
  ],
  deps = [
    "//:packages",
  ],
)

Run and build the binary:

$ bazel run //:app John
INFO: Analysed target //:app (0 packages loaded).
INFO: Found 1 target...
Target //:app up-to-date:
  bazel-bin/app.js
INFO: Elapsed time: 0.140s, Critical Path: 0.00s
INFO: Build completed successfully, 1 total action

INFO: Running command line: bazel-bin/app.js John
Hello John

Rules

js_library

js_library(
  name,
  srcs,
  deps = [],
)

Used to represent a set of JavaScript files and their dependencies.

ts_library

ts_library(name, srcs, deps = [], tsconfig = ...)

Used to generate the compiled JavaScript and declaration files for a set of TypeScript source files.

web_bundle

web_bundle(
  name,
  lib,
  entry,
  html_template,
  mode = "none",
  split_chunks = 0,
  public_path = "",
  library_name = "",
  library_target = "umd",
)

Used to compile a js_library to a JavaScript bundle to include in an HTML page.

You can run a webpack-dev-server with bazel run //target_server (append _server to your target name). Live reloading is supported if you use ibazel.

js_binary

Similar to web_bundle, but produces an executable JavaScript file (using Node).

js_script

js_script(cmd, lib)

Used to run a script (similarly to scripts in package.json).

js_test

js_test(cmd, lib)

Used to define a test. Arguments are identical to js_script.

npm_packages

npm_packages(name, package_json, yarn_lock)

Used to define NPM dependencies. Bazel will download the packages in its own internal directory.

npm_binary

npm_binary(install, binary)

Used to invoke an NPM binary (from node_modules/.bin/[binary]).