Skip to content

Bazel

skif lints the JavaScript workspace of a Bazel repository from its files: package.json, the workspace declaration, the tool configs and the sources, plus the Bazel files listed below. It never runs Bazel, and it reads Starlark as text without evaluating it. Its findings are the same before and after a build, whatever was built last.

The Bazel repository is the nearest directory at or above the workspace root, inside the git repository, that holds MODULE.bazel, REPO.bazel, WORKSPACE.bazel or WORKSPACE. Outside one, none of the Bazel handling on this page applies.

  • BUILD files of rules_js packages. When a root file of the Bazel repository names aspect_rules_js, the bazel plugin reads the BUILD.bazel and BUILD files of each package that has one at its top:
    • A node_modules label (":node_modules/esbuild", "//packages/app:node_modules/zod") or a package_json.bzl load ("@npm//packages/app:esbuild/package_json.bzl") uses that dependency in the package whose directory is the label’s Bazel package, and in no other: a nested package whose BUILD file holds a label of an enclosing package’s node_modules does not use its own listing through it. A dependency named this way that the label’s package does not list is unlisted-dependencies at the label’s line of that BUILD file, and skif explain-usage --dependency <name> --package <package> lists that file and line.
    • A comprehension that formats each string of a list literal with one %s names the formatted labels: [":node_modules/%s" % name for name in ["typescript", "vite"]] uses typescript and vite. Any other format template (":node_modules/%s" % name, ":node_modules/{}".format(name)), the patterns of a glob(...) ("node_modules/**", its exclude too) and a node_modules target that is no valid npm package name name no dependency.
    • The entry_point of js_binary, js_run_devserver and js_test is an entry, whose exports are public, when a literal names an existing file of the package ("src/main.ts" or ":src/main.ts").
    • The data of those rules and the srcs and data of js_library, ts_project and rules_angular’s ng_project are build sources: the files so named are used, and so is what they import, but they are no entries. Their unused exports and types are unused-exports and unused-types, and their members and duplicates are checked, as in any other module. A file that something else makes an entry (a main or bin of package.json, an entry glob) stays one.
    • A root BUILD file can name the files of a workspace member below it that has no BUILD file of its own (srcs = ["packages/foo/src/x.ts"]): they are entries or build sources of that member. One in a project of its own below the root (a nested root) is an entry or build source of that root under skif -r, so the unused exports of a build source there are reported as they are in a member.
    • The files of js_test count only outside --production, and so do those of any of these rules with testonly = True, a test target. The srcs and data of a test target also count through a glob([...]): its include patterns, relative to the BUILD file, are build sources, as a test runner’s file patterns are, so the *_spec.ts files that srcs = glob(["**/*_spec.ts"]) of a testonly ts_project builds and a jasmine_test runs are used. Its exclude patterns are not applied, and a glob of a target that is no test names nothing.
    • The deps of an ng_package (rules_angular) name the entry points it publishes: the index.ts of each Bazel package inside the npm package that a label names (":core", "//packages/common/http") is a production entry, whose exports are public, so the public_api.ts it re-exports is the package’s API.
  • Output trees. The bazel-bin, bazel-out, bazel-testlogs and bazel-<workspace> links at the top of the Bazel repository are never read. An import that reaches a file there, directly or through rootDirs, is generated code and is not followed.
  • Declared outputs. A relative import of a file that does not exist is not unresolved-imports when the nearest BUILD file at or above that file’s directory declares it in the outs, out or stdout of a call (also with another extension or none), or it lies below an out_dirs or out_dir there.
  • Toolchain pins. toolchain-pin-drift reads the MODULE.bazel, WORKSPACE.bazel and WORKSPACE at the workspace root: the pnpm_version of pnpm.pnpm(...) and npm_translate_lock(...) and the node_version of node.toolchain(...) and nodejs_register_toolchains(...). A pnpm 8 pin there next to packageManager: pnpm@9 is reported, at pnpm.pnpm pnpm_version.
  • Lockfile consumers. stray-lockfile does not report a member lockfile that Bazel installs from: a label of it in a root file, a BUILD file or a .bzl file they load, a $(location ...) of it, or a glob(...) of its package that matches it. The full list is under lockfiles and nested workspaces.
  • Convenience links as members. A * or glob segment of a workspace pattern follows links, as pnpm’s does, so after a build packages: ['*'] selects bazel-<name>. skif keeps it a member, leaves it out of the analysis, and nested-workspace-root reports it once with the detail BazelConvenienceLink.
  • Build tools in scripts. bazel, bazelisk and ibazel in a script are machine binaries, as docker and make are, so they are not unlisted-binaries. A listed @bazel/bazelisk or @bazel/ibazel is still used by the scripts that run them.
  • Macros and computed values. Only literals count, and the formatting comprehension above and the glob of a test target. Any other glob([...]), a select({...}), a variable, a comprehension of another shape (over a variable, with an if filter), or a target that a macro in a .bzl file defines names no dependency, entry, build source or output. Such a file can be unused-files and such an import unresolved-imports.
  • Labels in a sibling package. Each package reads only the BUILD files below its own directory, so "//packages/app:node_modules/zod" written in packages/web/BUILD.bazel does not count for packages/app. A nested package’s BUILD file still counts for the package above it, but gives it no entries or build sources.
  • Generated code. The imports of a file in bazel-bin are not judged. The dependencies its target names (srcs = [":node_modules/zod"]) are used instead.
  • .bazelignore. The JS analysis does not honour it: nested Bazel modules listed there are often pnpm workspaces of their own that skif -r should still lint. Only stray-lockfile reads it, to skip those directories when it lists BUILD files. Files under a .bazelignored directory without a package.json belong to the package above them; use [js] ignore for them (recipes).
  • Pins outside the root files. A pin in a loaded .bzl file, or in the files of a Bazel repository above the workspace, is not read by default (ADR 0011).
  • bazel query. skif never runs Bazel, so targets, sources and outputs that only a query or a build would show are not seen.

Each release attaches one archive per platform and checksums.txt (prebuilt binaries). A .tar.gz archive holds skif at its top level, so it can be fetched as a Bazel repository. With Bzlmod, in MODULE.bazel:

bazel_dep(name = "platforms", version = "<version>")
bazel_dep(name = "bazel_skylib", version = "<version>")
http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "skif_macos_arm64",
url = "https://github.com/polylint/skif/releases/download/v0.8.0/skif-aarch64-apple-darwin.tar.gz",
sha256 = "<the archive's line in checksums.txt>",
build_file_content = 'exports_files(["skif"])',
)
http_archive(
name = "skif_linux_x86_64",
url = "https://github.com/polylint/skif/releases/download/v0.8.0/skif-x86_64-unknown-linux-musl.tar.gz",
sha256 = "<the archive's line in checksums.txt>",
build_file_content = 'exports_files(["skif"])',
)

Add one repository per platform you build on: aarch64-apple-darwin, x86_64-apple-darwin, and the -unknown-linux-musl archives, which run on any Linux. The Windows archives are .zip files holding skif.exe. Then, in the root BUILD.bazel, pick the binary for the host:

load("@bazel_skylib//rules:native_binary.bzl", "native_binary")
config_setting(
name = "macos_arm64",
constraint_values = ["@platforms//os:macos", "@platforms//cpu:aarch64"],
)
config_setting(
name = "linux_x86_64",
constraint_values = ["@platforms//os:linux", "@platforms//cpu:x86_64"],
)
alias(
name = "skif_bin",
actual = select({
":macos_arm64": "@skif_macos_arm64//:skif",
":linux_x86_64": "@skif_linux_x86_64//:skif",
}),
)
native_binary(
name = "skif",
src = ":skif_bin",
out = "skif",
)

rules_multitool does the same from a lockfile: an entry per platform with "kind": "archive", the archive’s url and sha256, "file": "skif", and os and cpu. bazel run @multitool//tools/skif then runs it.

The npm package @polylint/skif is not tested through rules_js npm_translate_lock: it installs one platform package per target as an optional dependency, and that has not been checked under rules_js.

Terminal window
bazel run //:skif # lint
bazel run //:skif -- --fix # fix
bazel run //:skif -- -W packages/app --format json

bazel run starts a binary in its runfiles tree. When BUILD_WORKSPACE_DIRECTORY is set, the skif binary first changes to the directory you ran Bazel from (BUILD_WORKING_DIRECTORY, else the workspace root), as buildifier and gazelle do. The default . and every relative path on the command line (--config, --output, --format FORMAT=FILE) then resolve against the source tree, and --fix writes there. Run from a subdirectory, skif lints the workspace that holds it. The npm package’s skif bin does the same; the run() function of the npm package does not (ADR 0011).

This is the model to use for fixes: bazel run //:skif -- --fix. A fix inside a runfiles tree fails with refusing to write through a symlink, because runfiles are links into the source tree.

A test sees only the files given as data. skif needs every package.json, the workspace declaration, the lockfile, skif.toml, the tsconfigs and the sources. Include the Bazel root file and the BUILD files too, so the runfiles tree is a Bazel repository to skif and the Bazel handling above applies. A root glob() stops at Bazel package boundaries, so each package provides a filegroup:

packages/app/BUILD.bazel
filegroup(
name = "skif_inputs",
srcs = ["BUILD.bazel", "package.json"] + glob(["tsconfig*.json", "src/**"]),
visibility = ["//:__pkg__"],
)
BUILD.bazel
load("@bazel_skylib//rules:native_binary.bzl", "native_test")
native_test(
name = "skif_test",
src = ":skif_bin",
out = "skif_test_bin",
args = ["--cache"],
data = [
"BUILD.bazel",
"MODULE.bazel",
"package.json",
"pnpm-lock.yaml",
"pnpm-workspace.yaml",
"skif.toml",
"//packages/app:skif_inputs",
],
)

The test fails when skif exits non-zero: with an error finding, or with a warning under --fail-on-warnings. The runfiles tree has no .git, so skif lists the files by walking the directories instead of reading the git index.

Under bazel test (TEST_TMPDIR is set), --cache without --cache-location keeps its store in $TEST_TMPDIR/skif/, not in Bazel’s output tree. TEST_TMPDIR is cleared between test runs, so the cache saves parsing only within one run (ADR 0011).

Keeping the inputs complete is work: a file missing from data changes the findings. bazel run and CI read the source tree directly, so most repositories use those and keep a skif_test optional.

skif needs no Bazel build, so CI can run it outside Bazel, before or after the build, with the same result. Use the GitHub Action or any other install from the repository root:

- uses: actions/checkout@v7
- uses: polylint/skif@v0.8

Ignore the convenience links in git. skif skips them without this, since it does not enter linked directories when it lists files or looks for roots, but it keeps them out of other tools’ way:

bazel-*

Drop the bazel-<name> link from a * pattern, as nested-workspace-root suggests:

pnpm-workspace.yaml
packages:
- "*"
- "!bazel-*"

Declare generated files where skif can see them: a literal in the outs of the target in the BUILD file of the importing package, and the generated code’s dependencies as labels.

js_run_binary(
name = "schema",
tool = ":codegen",
srcs = [":node_modules/zod"],
outs = ["src/gen/schema.js"],
)

import "./gen/schema.js" from src/index.ts is then generated code, and zod is used. rootDirs pointing into bazel-bin is still what TypeScript needs to type-check the import; skif does not need it.

Ignore files of a .bazelignored directory that has no package.json:

[js]
ignore = ["e2e/coverage/**"]

Read a Bazel pin from a loaded .bzl file:

[rules.toolchain-pin-drift]
files = ["tools/versions.bzl"]

Turn the bazel plugin off:

[js.plugins]
bazel = false
  • Packages that rules_js hoists publicly (public_hoist_packages, .npmrc public-hoist-pattern) and that a package imports without listing are unlisted-dependencies, as in knip, unless [js] use-public-hoisting = true counts them as available ([js]). public_hoist_packages is read only as a dict literal in the root MODULE.bazel, WORKSPACE.bazel or WORKSPACE.

  • Macros, glob() (but for the include patterns of a test target’s), select() and variables in BUILD files are not evaluated (above).

  • A Bazel repository with a member lockfile that nothing names lists its directories for BUILD files on every run, until the lockfile is removed or allowed.

  • A bazel-* link member is left out of the analysis even when it was meant to be linted; !bazel-* is the supported layout.

  • Installing skif through rules_js is untested (above).

  • The exports of srcs and data files are judged, so an export that another Bazel target reads only through a module name that Bazel maps and skif does not resolve (a package name that an npm_package target gives and no package.json, tsconfig paths or [js] paths entry does) is unused-exports. Tag it @public, or name a tag of your own in the ignore-tags option of unused-exports:

    [rules]
    unused-exports = { ignore-tags = ["bazel"] }

The decisions are in ADR 0011 and ADR 0004.