Single packages and monorepos
skif [PATH] lints the project containing PATH (default .). The project is the nearest directory at or above
PATH that holds a package.json or declares a workspace. A directory declares a workspace with workspaces in
package.json or a pnpm-workspace.yaml.
- If the project declares a workspace, it is the root.
- Otherwise the root is the nearest ancestor workspace that lists the project as a member, after negations. An ancestor workspace does not claim projects it does not list.
- Otherwise the project is its own root.
The root is used for configuration, every reported path, every fix write and the install step, so the result does not depend on the current directory.
Configuration lookup
Section titled “Configuration lookup”skif.toml or .skif.toml is searched from the root upwards to the root of the git repository, and every file found
is merged, the nearest last. A file with root = true ends the search. Outside a repository the search covers the
root alone in a single-root run and the start directory in a multi-root run. A file above the repository is never
read. A member directory may hold a package file, and [[overrides]] select packages and files. See
Sharing configuration.
Package manager detection
Section titled “Package manager detection”First match wins:
[workspace] package-managerinskif.toml.- The root
package.jsonpackageManagerfield, thendevEngines.packageManager. - The package manager that
rush.jsonnames (pnpmVersion,npmVersionoryarnVersion), else thenpmClientof alerna.jsonthat declares the members. - Lockfile presence:
pnpm-lock.yaml,bun.lock/bun.lockb,yarn.lock,package-lock.json. - A
pnpm-workspace.yamlimplies pnpm. - A
.yarnrc.ymlor a.yarn/releasesdirectory implies Yarn (Berry), for checkouts that do not commityarn.lock. - A root
bunfig.tomlwith an[install]table implies Bun, for checkouts that do not commitbun.lock. Abunfig.tomlthat only configuresbun testor the runtime does not.
If nothing indicates a manager, skif does not guess npm. Rules and fixes that depend on the manager skip what
would be wrong for some manager; an npm workspace never receives a workspace:* specifier, and neither does
Yarn Classic (1.x), which has no workspace: protocol. Both link a member through a range its version satisfies, so
local-path-dependency replaces a path to a member with * there; under Yarn Classic, whose * does not match a
prerelease, a member with a prerelease version gets that exact version. Catalogs are read from the files of the active manager only: a
stale pnpm-workspace.yaml in a Yarn repository declares none.
Lockfile
Section titled “Lockfile”Discovery does not read the lockfile. Three checks do, on the first run that needs one: banned-dependency for a
[[version-groups]] entry with scope = "lockfile", unsynced-dependency-family for a [[dependency-families]]
entry with scope = "importer" or "lockfile", and stale-patched-dependencies when the root pnpm-workspace.yaml or
package.json (pnpm.patchedDependencies) declares patches. They read pnpm-lock.yaml of the root in lockfile format
9 (pnpm 9 to 12), and bun.lock in a Bun workspace. There stale-patched-dependencies reads the top-level
patchedDependencies of the root package.json, the only ones Bun applies, and checks them against bun.lock; the
two other checks walk the graph bun.lock records, following each dependency to the copy Bun installs for it (nested
below the package or the workspace package that gets its own copy, else the one at the top), so an importer reaches
what bun install puts in its node_modules. yarn.lock, package-lock.json, the binary bun.lockb and older pnpm
formats are not read; such a check then reports that nothing was checked, as it does when there is no lockfile or it
does not parse. From pnpm 11 on, pnpm-lock.yaml can hold two YAML documents: the package manager’s environment
(configDependencies, packageManagerDependencies) and then the project’s lockfile. skif reads the project’s
document and requires lockfile format 9 in both.
stale-patched-dependencies reports a patch whose name@version the lockfile no longer resolves (the patch stopped
applying after a bump) or resolves without a patch hash (in bun.lock: without the entry Bun records in its own
patchedDependencies when it applies a patch), a patch file that does not exist, a patch file outside the
allowed-patch-paths globs (the paths a build context copies), and a *.patch file no entry references in the
directories of the referenced patches and patches/ (or the patch-dirs you configure). The entries are reported at
their key.
Workspace patterns
Section titled “Workspace patterns”The patterns come from pnpm-workspace.yaml for a pnpm workspace, else from the workspaces of the root
package.json, a leftover pnpm-workspace.yaml, the projects of rush.json, and last the packages of a
lerna.json next to the root package.json (a Lerna monorepo without package-manager workspaces, as syncpack reads
it). lerna.json is read only when nothing before it declares members; an invalid one is then ignored.
Patterns follow pnpm semantics for every package manager: dir/* for direct children that contain a package.json,
dir/** for nested packages, and !pattern to remove matches. One exception follows Bun: in a Bun workspace a
negation does not remove a directory that a pattern names by its literal path (packages/tool), as bun install
keeps it. Bun also installs members outside the root: in a Bun workspace a pattern may start with .. segments
(../shared, ../libs/*). skif counts what such a pattern selects, so it is neither invalid nor unmatched, but does not
lint those members; lint their directory as a root of its own. Bun’s object form ("workspaces": { "packages": [...], "catalog": {...}, "catalogs": {...} })
and catalogs at the top level of the root package.json are both read. Wildcards never enter
node_modules or dot-directories, but a pattern that names a dot-directory (.vscode/extensions/*) does. The JS
analysis, which skips hidden directories other than tool configuration ones, then walks such a directory for the
members below it, and only for those.
missing-package-manifest reports a directory the patterns select that has content but no package.json. It leaves
out an Nx project, a directory with a project.json, and a grouping directory whose content is only directories the
patterns select too: with ["libs/*", "libs/*/*"], libs/cart holding the members libs/cart/feature and
libs/cart/ui is not reported, while a libs/cart/README.md next to them makes it a finding. In a Bun workspace it
also reports a member whose package.json has no name (or an empty one), with the detail NamelessBunMember: Bun
skips such a member without a warning, so none of its dependencies are installed. skif excludes the member from
analysis, as [workspace] ignore-packages would, and the unsafe fix names it after its directory.
What discovery cannot read does not stop the run, but it is not silent either: invalid-workspace-file (error)
reports a member package.json that is not valid JSON or cannot be read, at the syntax error, a pattern that cannot
be used (one that climbs out of the root with .., outside a Bun workspace, or has too many brace alternatives), where
it is written, and a
.yarnrc.yml that is not valid YAML. The package, the pattern’s matches or the Yarn catalogs are left out of the
run, so the run fails until the file is fixed, as sherif does.
Lerna is maintained (by Nrwl, the company behind Nx) and reads its own lerna.json. Its package list comes from
packages in lerna.json first, then from pnpm-workspace.yaml when npmClient is pnpm, then from the
workspaces of package.json. skif follows the package manager instead, because it installs and links the members,
and reads lerna.json only when nothing else declares them (see Workspace patterns).
When both declare members and select different packages, lerna-packages-mismatch (warn) reports it at packages in
lerna.json, naming both lists and the packages only one of them selects: lerna run and lerna publish act on
packages the package manager does not install, or skip members it does. Delete packages from lerna.json to have
Lerna follow the workspaces, or make the two lists select the same packages. A lerna.json with useWorkspaces: true
is not reported, since Lerna before 7 then follows the package manager.
stale-lerna-config (warn) reports what the installed Lerna rejects. Lerna 7 and later fail on useWorkspaces in
lerna.json (ECONFIGWORKSPACES; lerna repair deletes the key) and without a version (ENOVERSION). Lerna 9
removed lerna bootstrap, lerna add and lerna link; a root or member script that runs one, also through npx,
pnpm exec or yarn, is reported at the script. The release is read from node_modules/lerna/package.json, else
from the lowest version the root package.json admits for lerna; without either, or with a tag such as latest,
nothing is reported. A script that runs a pinned release (npx lerna@6 bootstrap) is not reported. See also
Turborepo, Nx and Lerna.
Lockfiles and nested workspaces
Section titled “Lockfiles and nested workspaces”Every package manager installs a workspace from one lockfile at its root. stray-lockfile reports any other
lockfile it finds: one in a member’s directory (package-lock.json, npm-shrinkwrap.json, yarn.lock,
pnpm-lock.yaml, bun.lock, bun.lockb), and one at the root that another manager than the detected one writes
(package-lock.json next to pnpm-lock.yaml in a pnpm workspace). Either of npm’s two lockfiles is accepted at the
root, and so is either of Bun’s. Next to each other, the one the manager ignores is reported: package-lock.json beside
npm-shrinkwrap.json, which npm installs from, and a binary bun.lockb beside bun.lock, which Bun installs from.
Without a detected manager the root lockfiles are not judged. Its unsafe fix deletes the file.
A member’s lockfile that a build installs from is not reported, so the fix never deletes it. skif reads the build files and runs nothing:
- in a Bazel repository, a label of the lockfile,
"//libs/a:pnpm-lock.yaml"(also@//,@@//,@<name>//with the name of themodule(...)call, and"//:libs/a/pnpm-lock.yaml"), in theMODULE.bazel,REPO.bazel,WORKSPACEorWORKSPACE.bazelof the Bazel repository, aBUILDorBUILD.bazelfile of the lockfile’s directory or one above, or a.bzlfile those load (load("//tools:deps.bzl", ...), transitively), as rules_js’snpm_translate_lock(pnpm_lock = ...)takes it. The Bazel repository is the nearest directory at or above the root, inside the git repository, with aMODULE.bazel,REPO.bazel,WORKSPACEorWORKSPACE.bazel; without one, no Bazel file is read. Labels are relative to it, so in a workspace atjs/of a Bazel repository the label is//js/libs/a:pnpm-lock.yaml. A label also counts inside a longer string where a location function expands it, as in agenrule’scmd = "cp $(location //libs/a:pnpm-lock.yaml) $@"(also$(execpath ...),$(rootpath ...),$(rlocationpath ...)and their plural forms); - its path relative to a
BUILDorBUILD.bazelfile of its own directory or one above ("pnpm-lock.yaml",":pnpm-lock.yaml","a/pnpm-lock.yaml"), as inexports_filesorsrcs; - a
glob(...)in theBUILDfile of its package (the nearest directory at or above it with aBUILDfile) whose include patterns match it and whose exclude patterns do not (glob(["**/*.yaml"])); - when none of those name it, a label of it in any
BUILDfile of the Bazel repository, or in a.bzlfile such a file loads: the repository is then listed for itsBUILDfiles, without entering hidden directories,node_modules, symbolic links (thebazel-*links) or the directories.bazelignorenames; - a
COPYorADDof it, by name or by a glob such aspnpm-lock.yaml*, in a Dockerfile (Dockerfile,Dockerfile.*,*.Dockerfile,Containerfile) of its own directory, or in any Dockerfile with the path from the workspace root (COPY libs/a/pnpm-lock.yaml ./), for a build whose context is the root; - a
COPY . .in a Dockerfile of its own directory followed by an install with its package manager (pnpm install,npm ci,yarn,bun install); - either of the last two in a Dockerfile elsewhere that a build gives the lockfile’s directory as its context: a
docker build,docker buildx buildorpodman buildcommand in a script or workflow the toolchain rules read (docker build -f docker/web.Dockerfile apps/web, both paths from the workspace root), or a service of a Compose file at the root (compose.yaml,compose.yml,docker-compose.yaml,docker-compose.yml) whosebuildnames the directory, with itsdockerfilerelative to that context.
A copy from another stage (--from) does not count. Comments, docstrings and the names in an exclude = [...] list
are skipped. A directory is listed for Bazel files only while a lockfile is left that the files Bazel reads for it do
not name. An allow entry for a lockfile a build names is reported as stale, since the rule would not report the file
without it.
nested-workspace-root reports a pnpm-workspace.yaml in a member’s directory: pnpm takes the nearest one above the
working directory, so an install in that member leaves the root workspace. skif lints such a member as a root of its
own in a recursive run, and the enclosing workspace still reports the file; the member’s own lockfile is left to that
root. A nested workspace that the patterns do not select is an independent project and is not reported. In a Bun
workspace it also reports a member package.json that declares workspaces: Bun reads the field from the root
package.json only, so it never installs the packages such a member lists.
After a Bazel build the root holds convenience links (bazel-bin, bazel-out, bazel-testlogs and bazel-<name>,
the last a link to the execroot, which mirrors the root). A * or glob segment of a workspace pattern follows links to
directories, as pnpm’s does, so packages: ['*'] makes such a link a member. skif keeps it a member, excludes it from
analysis so the root’s findings are not repeated under it, and nested-workspace-root reports it once, at its
package.json, with the detail BazelConvenienceLink. Add !bazel-* to the patterns to drop it. The
Bazel guide covers the rest of a Bazel repository.
Both rules look at the root and the directories the workspace patterns select, not deeper, and skip files a
.gitignore, an .ignore or .git/info/exclude excludes and members [workspace] ignore-packages excludes. A
project that is installed on its own on purpose is better excluded from the workspace patterns; when it has to stay,
list the file under allow:
[rules.stray-lockfile]allow = [{ name = "tools/codegen/package-lock.json", reason = "the build installs this tool on its own" }]An entry is a path or a glob relative to the root (examples/*/package-lock.json; * also crosses /), as a string or
with a reason. It matches its own path literally first, so app/[id]/package-lock.json names that file, and then as
a glob. A pattern that is not a valid glob, starts with ! or is $LOCAL is a configuration error. An entry that matches
no file the rule would report is itself reported, at the configuration file, unless that file was inherited from a
directory above the root.
Monorepo configuration
Section titled “Monorepo configuration”[workspace]ignore-packages = ["examples/*"]
[policy]prefer = "highest"
[[version-groups]]label = "Pin react across the repo"dependencies = ["react", "react-dom"]policy = "pinned"pin = "19.1.0"
[[semver-groups]]label = "Caret ranges for libraries"packages = ["packages/*"]range = "^"
[catalog]mode = "prefer"min-packages = 3Single packages
Section titled “Single packages”A package that declares no workspace is linted on its own; skif does not require a workspaces field or a
pnpm-workspace.yaml. A pnpm-workspace.yaml that holds only settings and no packages: key counts as no
declaration when it finds no package besides the root. In this single-package mode root-package-private-field and
root-package-dependencies do not report, because a standalone package is published and keeps its dependencies in
its own package.json. The other rules run unchanged; turn off those that do not fit with [rules].
Several projects
Section titled “Several projects”A repository can hold independent projects with no workspace at the top. skif -r (--recursive) lints every
workspace and standalone package at or below the start path in one run, and so does a plain skif started where
neither the path nor any ancestor holds a package.json or a workspace declaration.
skif -r # every root below the current directoryskif -r services # every root below services/skif -r --format json # one document with a "roots" array- A root is a workspace that no outer workspace lists as a member, or a package that declares no workspace, is listed by no workspace and does not lie inside a workspace member. Members are never roots of their own.
- A directory that declares a workspace is always a root of its own, also when it sits inside another workspace. A
workspace needs no root
package.json: apnpm-workspace.yamlor arush.jsonalone is enough, and the members are linted while the rules about the root manifest are skipped. - A
package.jsonthat makes no package is no root when anotherpackage.jsonat or below the start path lies above it: one holding onlytype,sideEffectsorimports({"type": "commonjs"}in ascriptsfolder), or onlymain,module,types,typingsorbrowserin a directory the package above publishes as a subpath. Its files belong to the package above, which lints them once. With nopackage.jsonabove it, such a directory is a root of its own. - A standalone package below another root (an example, a template) is linted, but
root-package-manager-fielddoes not report for it; the rule still reports for every workspace and for the outermost root. - The search skips
node_modules, hidden directories, symbolic links, anything a.gitignoreor.ignoreexcludes, and the directories named by[workspace] discover-ignore(by default__fixtures__,fixtures,__mocks__and__snapshots__). It goes at most 32 directories deep; the directories it did not enter below that limit are named on stderr and in thetruncatedarray of the JSON document. - Below the start path the search also skips the output of
turbo prune --docker: thejsonandfulltrees of a directory without apackage.jsonthat holds a lockfile next to them (out/by default). Both trees copy packages of the workspace they were pruned from. Start the run in that directory to lint them. - A root that cannot be loaded does not stop the others: it is listed in the
errorsarray of the JSON document and the exit code is2. --config <FILE>makes that file the configuration of every root. Its[js.workspaces]keys andignore-workspacesglobs are relative to the start directory, so[js.workspaces."."]configures the root there and[js.workspaces."tools/sub"]the root intools/sub; started fromtools/, the same root is"sub". Astale-js-configfinding about the file is reported once for the run, and a stale entry only when every root that judged it found it stale.- Roots are linted in parallel and merged into one report in path order. Paths are relative to the invocation
directory, and the exit code is the worst over the roots.
--max-warningsbounds the warnings of the whole run. --fixplans, writes and runs the package manager’s install per root.- If no root is found, skif exits with code
2and says no workspace or package was found.
Nx workspaces
Section titled “Nx workspaces”How to run skif next to Nx, and its limits there, are in Turborepo, Nx and Lerna.
skif reads Nx’s nx.json, the nx key of package.json and the project.json files of a package when the nx
plugin is enabled (nx, @nx/* or @nrwl/* is a dependency, or [js.plugins] nx = true). The projects are found
where skif looks for source files: a project.json below a gitignored or hidden directory, node_modules or build
output at the top of a package is not read. A package reads its own project.json and those of its projects without
a package.json; a workspace member’s are the member’s.
- The executors, generators and
nx.jsonplugins name packages, unless they name a local plugin: a path relative to the workspace root (./tools/nxp/index.ts,./tools/executors/echo:echo) or apathsalias of the roottsconfig.base.json(elsetsconfig.json) that points at an existing file or directory. A local plugin inpluginsis an entry; for it and for a local executor or generator, theexecutors,builders,generatorsandschematicscollections that itspackage.jsonnames are read, and theirimplementation,batchImplementationandfactoryfiles are entries. A workspace package’s own collections are read as well. - A target’s
commandandrun-commandscommands are scripts that run in the workspace root, or in itscwd;{workspaceRoot}and{projectRoot}stand for the root and the project’s directory. ThemainandadditionalEntryPointsoptions of a build are entries.tsConfig,jestConfig,webpackConfig,cypressConfigandeslintConfigare read as the configs of those tools, andconfigFile,configandconfigDirof the@nx/vite,@nx/playwrightand@nx/storybookexecutors as Vite, Playwright and Storybook configs. These paths are relative to the workspace root, also in a member’sproject.json. - A project in a package-based workspace has its own
package.jsonand is a workspace member, linted as any other. - A project of an integrated workspace has no
package.json: the root lists its dependencies. Its directory is a scope of the root. Every plugin reads the project’s configs there (vite.config.ts,index.html,eslint.config.mjs,jest.config.ts,.babelrc,tsconfig.json), as for a package, and what they name and make entries counts for the root. A plugin with no config file in the project and no default entries is not run there, unless a target of the project runs the tool’s Nx executor (@nx/vite:build): the tool’s conventions then apply as without a config, so Vite’sindex.htmlnames the app’s entry. A config of the project that cannot be read leaves only the project’s files unjudged. - The root
jest.config.tsthat Nx generates (projects: await getJestProjectsAsync(), or[...getJestProjects(), ...]) reads the Jest config of each project: a project’sjestConfigoption and thejest.config.*in its directory. - A
cypress.config.*whosee2espreadsnxE2EPreset(__filename, …)(@nx/cypress/plugins/cypress-preset) has the preset’ssupportFileandspecPattern:src/support/e2e.{js,ts}andsrc/**/*.cy.{js,jsx,ts,tsx}, below thecypressDiroption when it is a string. A key written after the spread wins over the preset. - A buildable library with a
package.jsonthat is not a workspace member is a separate project, like any directory with its own manifest: its files are not analysed.