Skip to content

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.

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.

First match wins:

  1. [workspace] package-manager in skif.toml.
  2. The root package.json packageManager field, then devEngines.packageManager.
  3. The package manager that rush.json names (pnpmVersion, npmVersion or yarnVersion), else the npmClient of a lerna.json that declares the members.
  4. Lockfile presence: pnpm-lock.yaml, bun.lock / bun.lockb, yarn.lock, package-lock.json.
  5. A pnpm-workspace.yaml implies pnpm.
  6. A .yarnrc.yml or a .yarn/releases directory implies Yarn (Berry), for checkouts that do not commit yarn.lock.
  7. A root bunfig.toml with an [install] table implies Bun, for checkouts that do not commit bun.lock. A bunfig.toml that only configures bun test or 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.

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.

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.

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 the module(...) call, and "//:libs/a/pnpm-lock.yaml"), in the MODULE.bazel, REPO.bazel, WORKSPACE or WORKSPACE.bazel of the Bazel repository, a BUILD or BUILD.bazel file of the lockfile’s directory or one above, or a .bzl file those load (load("//tools:deps.bzl", ...), transitively), as rules_js’s npm_translate_lock(pnpm_lock = ...) takes it. The Bazel repository is the nearest directory at or above the root, inside the git repository, with a MODULE.bazel, REPO.bazel, WORKSPACE or WORKSPACE.bazel; without one, no Bazel file is read. Labels are relative to it, so in a workspace at js/ 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 a genrule’s cmd = "cp $(location //libs/a:pnpm-lock.yaml) $@" (also $(execpath ...), $(rootpath ...), $(rlocationpath ...) and their plural forms);
  • its path relative to a BUILD or BUILD.bazel file of its own directory or one above ("pnpm-lock.yaml", ":pnpm-lock.yaml", "a/pnpm-lock.yaml"), as in exports_files or srcs;
  • a glob(...) in the BUILD file of its package (the nearest directory at or above it with a BUILD file) 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 BUILD file of the Bazel repository, or in a .bzl file such a file loads: the repository is then listed for its BUILD files, without entering hidden directories, node_modules, symbolic links (the bazel-* links) or the directories .bazelignore names;
  • a COPY or ADD of it, by name or by a glob such as pnpm-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 build or podman build command 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) whose build names the directory, with its dockerfile relative 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.

[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 = 3

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].

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.

Terminal window
skif -r # every root below the current directory
skif -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: a pnpm-workspace.yaml or a rush.json alone is enough, and the members are linted while the rules about the root manifest are skipped.
  • A package.json that makes no package is no root when another package.json at or below the start path lies above it: one holding only type, sideEffects or imports ({"type": "commonjs"} in a scripts folder), or only main, module, types, typings or browser in a directory the package above publishes as a subpath. Its files belong to the package above, which lints them once. With no package.json above 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-field does 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 .gitignore or .ignore excludes, 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 the truncated array of the JSON document.
  • Below the start path the search also skips the output of turbo prune --docker: the json and full trees of a directory without a package.json that 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 errors array of the JSON document and the exit code is 2.
  • --config <FILE> makes that file the configuration of every root. Its [js.workspaces] keys and ignore-workspaces globs are relative to the start directory, so [js.workspaces."."] configures the root there and [js.workspaces."tools/sub"] the root in tools/sub; started from tools/, the same root is "sub". A stale-js-config finding 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-warnings bounds the warnings of the whole run.
  • --fix plans, writes and runs the package manager’s install per root.
  • If no root is found, skif exits with code 2 and says no workspace or package was found.

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.json plugins name packages, unless they name a local plugin: a path relative to the workspace root (./tools/nxp/index.ts, ./tools/executors/echo:echo) or a paths alias of the root tsconfig.base.json (else tsconfig.json) that points at an existing file or directory. A local plugin in plugins is an entry; for it and for a local executor or generator, the executors, builders, generators and schematics collections that its package.json names are read, and their implementation, batchImplementation and factory files are entries. A workspace package’s own collections are read as well.
  • A target’s command and run-commands commands are scripts that run in the workspace root, or in its cwd; {workspaceRoot} and {projectRoot} stand for the root and the project’s directory. The main and additionalEntryPoints options of a build are entries. tsConfig, jestConfig, webpackConfig, cypressConfig and eslintConfig are read as the configs of those tools, and configFile, config and configDir of the @nx/vite, @nx/playwright and @nx/storybook executors as Vite, Playwright and Storybook configs. These paths are relative to the workspace root, also in a member’s project.json.
  • A project in a package-based workspace has its own package.json and 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’s index.html names the app’s entry. A config of the project that cannot be read leaves only the project’s files unjudged.
  • The root jest.config.ts that Nx generates (projects: await getJestProjectsAsync(), or [...getJestProjects(), ...]) reads the Jest config of each project: a project’s jestConfig option and the jest.config.* in its directory.
  • A cypress.config.* whose e2e spreads nxE2EPreset(__filename, …) (@nx/cypress/plugins/cypress-preset) has the preset’s supportFile and specPattern: src/support/e2e.{js,ts} and src/**/*.cy.{js,jsx,ts,tsx}, below the cypressDir option when it is a string. A key written after the spread wins over the preset.
  • A buildable library with a package.json that is not a workspace member is a separate project, like any directory with its own manifest: its files are not analysed.