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.
What skif reads
Section titled “What skif reads”BUILDfiles of rules_js packages. When a root file of the Bazel repository namesaspect_rules_js, thebazelplugin reads theBUILD.bazelandBUILDfiles of each package that has one at its top:- A
node_moduleslabel (":node_modules/esbuild","//packages/app:node_modules/zod") or apackage_json.bzlload ("@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 whoseBUILDfile holds a label of an enclosing package’snode_modulesdoes not use its own listing through it. A dependency named this way that the label’s package does not list isunlisted-dependenciesat the label’s line of thatBUILDfile, andskif explain-usage --dependency <name> --package <package>lists that file and line. - A comprehension that formats each string of a list literal with one
%snames the formatted labels:[":node_modules/%s" % name for name in ["typescript", "vite"]]usestypescriptandvite. Any other format template (":node_modules/%s" % name,":node_modules/{}".format(name)), the patterns of aglob(...)("node_modules/**", itsexcludetoo) and anode_modulestarget that is no valid npm package name name no dependency. - The
entry_pointofjs_binary,js_run_devserverandjs_testis an entry, whose exports are public, when a literal names an existing file of the package ("src/main.ts"or":src/main.ts"). - The
dataof those rules and thesrcsanddataofjs_library,ts_projectand rules_angular’sng_projectare build sources: the files so named are used, and so is what they import, but they are no entries. Their unused exports and types areunused-exportsandunused-types, and their members and duplicates are checked, as in any other module. A file that something else makes an entry (amainorbinofpackage.json, anentryglob) stays one. - A root
BUILDfile can name the files of a workspace member below it that has noBUILDfile 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 underskif -r, so the unused exports of a build source there are reported as they are in a member. - The files of
js_testcount only outside--production, and so do those of any of these rules withtestonly = True, a test target. Thesrcsanddataof a test target also count through aglob([...]): its include patterns, relative to theBUILDfile, are build sources, as a test runner’s file patterns are, so the*_spec.tsfiles thatsrcs = glob(["**/*_spec.ts"])of atestonlyts_projectbuilds and ajasmine_testruns are used. Itsexcludepatterns are not applied, and aglobof a target that is no test names nothing. - The
depsof anng_package(rules_angular) name the entry points it publishes: theindex.tsof each Bazel package inside the npm package that a label names (":core","//packages/common/http") is a production entry, whose exports are public, so thepublic_api.tsit re-exports is the package’s API.
- A
- Output trees. The
bazel-bin,bazel-out,bazel-testlogsandbazel-<workspace>links at the top of the Bazel repository are never read. An import that reaches a file there, directly or throughrootDirs, is generated code and is not followed. - Declared outputs. A relative import of a file that does not exist is not
unresolved-importswhen the nearestBUILDfile at or above that file’s directory declares it in theouts,outorstdoutof a call (also with another extension or none), or it lies below anout_dirsorout_dirthere. - Toolchain pins.
toolchain-pin-driftreads theMODULE.bazel,WORKSPACE.bazelandWORKSPACEat the workspace root: thepnpm_versionofpnpm.pnpm(...)andnpm_translate_lock(...)and thenode_versionofnode.toolchain(...)andnodejs_register_toolchains(...). A pnpm 8 pin there next topackageManager: pnpm@9is reported, atpnpm.pnpm pnpm_version. - Lockfile consumers.
stray-lockfiledoes not report a member lockfile that Bazel installs from: a label of it in a root file, aBUILDfile or a.bzlfile they load, a$(location ...)of it, or aglob(...)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 buildpackages: ['*']selectsbazel-<name>. skif keeps it a member, leaves it out of the analysis, andnested-workspace-rootreports it once with the detailBazelConvenienceLink. - Build tools in scripts.
bazel,bazeliskandibazelin a script are machine binaries, asdockerandmakeare, so they are notunlisted-binaries. A listed@bazel/bazeliskor@bazel/ibazelis still used by the scripts that run them.
What skif does not read
Section titled “What skif does not read”- Macros and computed values. Only literals count, and the formatting comprehension above and the
globof a test target. Any otherglob([...]), aselect({...}), a variable, a comprehension of another shape (over a variable, with aniffilter), or a target that a macro in a.bzlfile defines names no dependency, entry, build source or output. Such a file can beunused-filesand such an importunresolved-imports. - Labels in a sibling package. Each package reads only the
BUILDfiles below its own directory, so"//packages/app:node_modules/zod"written inpackages/web/BUILD.bazeldoes not count forpackages/app. A nested package’sBUILDfile still counts for the package above it, but gives it no entries or build sources. - Generated code. The imports of a file in
bazel-binare 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 thatskif -rshould still lint. Onlystray-lockfilereads it, to skip those directories when it listsBUILDfiles. Files under a.bazelignored directory without apackage.jsonbelong to the package above them; use[js] ignorefor them (recipes).- Pins outside the root files. A pin in a loaded
.bzlfile, 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.
Installing skif for Bazel
Section titled “Installing skif for Bazel”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.
Running skif
Section titled “Running skif”bazel run
Section titled “bazel run”bazel run //:skif # lintbazel run //:skif -- --fix # fixbazel run //:skif -- -W packages/app --format jsonbazel 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.
bazel test
Section titled “bazel test”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:
filegroup( name = "skif_inputs", srcs = ["BUILD.bazel", "package.json"] + glob(["tsconfig*.json", "src/**"]), visibility = ["//:__pkg__"],)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.8Recipes
Section titled “Recipes”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:
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 = falseKnown limits
Section titled “Known limits”-
Packages that rules_js hoists publicly (
public_hoist_packages,.npmrcpublic-hoist-pattern) and that a package imports without listing areunlisted-dependencies, as in knip, unless[js] use-public-hoisting = truecounts them as available ([js]).public_hoist_packagesis read only as a dict literal in the rootMODULE.bazel,WORKSPACE.bazelorWORKSPACE. -
Macros,
glob()(but for the include patterns of a test target’s),select()and variables inBUILDfiles are not evaluated (above). -
A Bazel repository with a member lockfile that nothing names lists its directories for
BUILDfiles 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
srcsanddatafiles 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 annpm_packagetarget gives and nopackage.json,tsconfigpathsor[js] pathsentry does) isunused-exports. Tag it@public, or name a tag of your own in theignore-tagsoption ofunused-exports:[rules]unused-exports = { ignore-tags = ["bazel"] }