Skip to content

Configuration

skif reads TOML files named skif.toml or .skif.toml. A root takes the files from its own directory up to the root of the git repository and merges them (see Layered configuration). Having both names in one directory is an error naming both paths. There is no package.json key and no JSON, YAML or JavaScript variant, and skif does not read sherif, syncpack or knip configuration while linting; skif migrate translates it once (see the migration guide). skif init writes a starter file and skif schema prints its JSON Schema.

Keys are kebab-case, matching rule ids. Unknown keys and wrong types are errors that name the file, line and key.

Defaults, then the files, then the command line (defaults < files < CLI). Each layer sets only the keys it contains, and arrays replace rather than append, except where a key says otherwise (see below). Within the files, the order is the base of each file from the farthest to the nearest, then [js.workspaces], then package files. [[overrides]] apply on top of the base to the packages and files they select.

skif init writes a #:schema directive, so editors with Taplo or Even Better TOML validate and complete the file. Print the schema with skif schema.

Section Holds
[workspace] ignore-packages, extend-ignore-packages, package-manager, discover-ignore
[lint] fail-on-warnings, max-level, require-ignore-reasons
[rules] Per-rule levels and options
[[ignore]] Suppressions
[policy] prefer, dependency-types, override-reading
[[version-groups]] Version policies per dependency group
[[semver-groups]] Range policies per dependency group
[[custom-types]] Manifest fields that hold versions and take part in the version policies
[catalog] Catalog enforcement
[workspace-protocol] workspace: protocol policy
[[dependency-families]] Packages that must share a version
[update] minimum-release-age, max-concurrent-requests for skif update
[[update-groups]] How far skif update may move each dependency group
[format] How package-json-format and skif format lay out package.json
[js] JavaScript analysis
root, extends, reset How files combine
[[overrides]] Rule levels, severity caps, suppressions and JS inputs for selected packages or files
[workspace]
ignore-packages = ["examples/*", "!examples/keep"]
package-manager = "pnpm" # npm | pnpm | yarn | bun; overrides detection
discover-ignore = ["fixtures", "e2e/cases"] # directories `skif -r` does not search for roots

discover-ignore takes gitignore-style patterns relative to the directory the run starts in: a bare name matches at any depth, a pattern with a slash is anchored there, and ! re-includes. It replaces the default list (__fixtures__, fixtures, __mocks__, __snapshots__); [] skips nothing. It is read from the configuration file that governs the start directory and only affects root discovery in a recursive run.

[lint]
fail-on-warnings = true # exit non-zero when only warnings were reported
max-level = "warn" # cap the severity of every finding of the root
require-ignore-reasons = true # fail when a suppression has no `reason`, as --require-ignore-reasons does

require-ignore-reasons makes the suppressions that can carry a reason say why they exist: an [[ignore]] entry, also one of an override, and an entry of the [js] lists ignore-files, ignore-dependencies, ignore-binaries, ignore-unresolved, ignore-workspaces and ignore-members, and extend-ignore-dependencies, extend-ignore-binaries and extend-ignore-unresolved, at the top level, per workspace and in overrides, and the allow entries of a rule (stray-lockfile, nested-workspace-root). [workspace] ignore-packages and [js] ignore take plain globs and are not checked. A run with an entry that has no reason fails with exit code 2, naming the entry (js.ignore-dependencies[1] `left-pad`: no `reason` ). The check reads the merged configuration, so the key and position are those of the merged list: an entry added with extend-ignore-dependencies or inherited through extends is named by the list it was merged into, and its name finds it in the files. The key and --require-ignore-reasons do the same; either one turns the check on.

A rule is a level string, or a table with a level and the rule’s own options. severity is accepted as an alias of level; setting both in one table is an error, and neither name can be a rule option.

[rules]
unsorted-dependencies = "warn" # off | info | warn | error
empty-dependencies = "off"
member-toolchain-fields = { level = "error", mode = "match-root" }
unused-exports = { ignore-tags = ["lintignore"] }

Rules with options:

Rule Option Values
member-toolchain-fields mode forbid (default) reports every packageManager or engines field a private member declares; match-root allows a field equal to the root’s.
stray-lockfile, nested-workspace-root allow Paths or globs, relative to the workspace root, of files kept on purpose: a string or { name, reason }, matched as a literal path first and then as a glob. An invalid glob, a ! pattern or $LOCAL is a configuration error; an entry that matches no file the rule would report is reported. See lockfiles and nested workspaces.
stale-patched-dependencies patch-dirs Directories, relative to the root, searched for *.patch files no patchedDependencies entry references. Empty (default) means the directories of the referenced patches and patches.
stale-patched-dependencies allowed-patch-paths Globs, relative to the root, that every patch file must match (["patches/**"], the paths a build context copies); empty (default) allows any path.
unused-exports, unused-types ignore-tags JSDoc tag names, without the @ (a list of strings), that exempt an export. It is read from unused-exports and applies to unused-types as well. public, beta, alpha and alias always exempt, and alias also keeps an export out of duplicate-exports.
unused-exports, unused-types include-tags JSDoc tag names; when set, only exports carrying one of them are reported, and only such enum and namespace members (knip’s --tags +name). A tag named here is judged even when it would exempt (public, beta, alpha, alias, internal in production mode), so include-tags = ["public"] reports the unused @public exports; knip reports none of them.
toolchain-pin-drift, foreign-package-manager-command kinds The kinds of file read at their usual places: version-files, dockerfiles, workflows, shell-scripts, bazel (the root’s MODULE.bazel, WORKSPACE.bazel and WORKSPACE, read for the pnpm_version of pnpm.pnpm(...) and npm_translate_lock(...) and the node_version of node.toolchain(...) and nodejs_register_toolchains(...); through files also .bzl and *.MODULE.bazel files). Default: version-files, dockerfiles, workflows and bazel for toolchain-pin-drift, dockerfiles, workflows and shell-scripts for foreign-package-manager-command.
toolchain-pin-drift, foreign-package-manager-command files More files to read, as globs relative to the workspace root (["deploy/**"]), whatever their kind.
toolchain-pin-drift, foreign-package-manager-command ignore-files Files to report nothing in, as globs relative to the workspace root; an entry is a string or { name = "...", reason = "..." }.

An unknown option is an error that names the rule.

An unknown rule id is rejected with a closest-match suggestion. See the rules for ids.

toolchain-pin-drift and foreign-package-manager-command read the files beside the manifests: in the root and every package directory the version files (.nvmrc, .node-version, .bun-version, .tool-versions, mise.toml, .mise.toml), Dockerfiles (Dockerfile, Dockerfile.*, *.Dockerfile, Containerfile) and *.sh, the last two also in their docker and scripts subdirectories, and the root’s .github/workflows/*.yml. A Dockerfile pins Node with FROM node:<version> and Bun with FROM oven/bun:<version>. A file below a directory with a package.json that is not a workspace package belongs to another project and is not read. Every one of these files takes # comments, which suppress a finding there; the reason after -- is required, and a comment without one suppresses nothing:

# skif-ignore-next-line toolchain-pin-drift -- the base image is pinned by the platform team
FROM node:18-alpine
# skif-ignore-next-line foreign-package-manager-command -- fallback for the 1.x release branch
RUN npm ci

# skif-ignore-file <rule> -- <reason> covers the whole file, and a comment without rule ids covers every toolchain rule. foreign-package-manager-command does not report read-only commands (npm view, npm whoami, yarn info) or a global install of the workspace’s own manager (npm install -g pnpm@9). See ADR 0006.

Each entry narrows by rules, packages, dependencies and files. An empty list does not narrow that dimension, but at least one list must be set. files matches the path of the file a finding is located in, relative to the workspace root (src/legacy/**), as written in every configuration file: unlike the files of [[overrides]], it is not anchored at the file that declares it.

[[ignore]]
rules = ["types-in-dependencies"]
packages = ["legacy-app"]
[[ignore]]
dependencies = ["left-pad"]
reason = "pinned until the legacy importer is gone"

reason is optional and records why the entry exists. --require-ignore-reasons and [lint] require-ignore-reasons fail a run on an entry without one, and on an entry of a [js] ignore list without one, so a baseline of suppressions can be reviewed and ratcheted down. Entries that flags add are exempt. skif baseline writes such entries for the current findings into a file of their own and keeps it from growing (see the CLI reference).

A dependencies pattern of the form name@specifier matches only the instances written with that specifier (react@^17.0.2); a bare name matches every version.

[policy]
prefer = "highest" # highest | lowest
dependency-types = ["peer"] # empty means prod, dev and local; name peer or optional to include them
override-reading = "skif" # skif | syncpack; how resolutions, overrides and pnpm-overrides entries are read

dependency-types (here and in version and semver groups) names where a version is declared. Each entry may be negated with !:

Type Selects
prod, dev, peer, optional The four dependency sections
local A package’s own version (syncpack’s local)
resolutions resolutions of package.json (yarn)
overrides overrides of package.json (npm, including nested objects)
pnpm-overrides pnpm.overrides of package.json and overrides of pnpm-workspace.yaml (syncpack: pnpmOverrides)
any [[custom-types]] name The versions that custom type reads

A group that names a type governs it. The catch-all group, and a group that names no type, cover prod, dev and the own versions; a type outside those is covered only when [policy] dependency-types names it. A [policy] dependency-types list that does not select local (["prod", "dev"], ["!local"]) takes the own versions out as it takes out the sections it does not name: no dependent is then compared with the version of the workspace package it names, as with syncpack’s --dependency-types prod,dev. The two are not the same: a list of negations only starts, as in syncpack, from every dependency section, so ["!local"] also brings in peerDependencies and optionalDependencies; write ["prod", "dev"] to keep the default sections. syncpack covers every type by default, so a syncpack configuration that relies on that needs dependency-types = ["prod", "dev", "resolutions", "overrides", "pnpm-overrides"] here. The dependency of an override entry is the package its selector names (react@<18, parent>react, **/react are react); a nested npm object’s . entry belongs to its parent. Only string values are instances, and a fix edits the entry in place, in pnpm-workspace.yaml for its overrides. Values that are references rather than versions (npm’s $name, pnpm’s -) are skipped, and the overrides of pnpm-workspace.yaml are read only when pnpm is the package manager. A group that names no type covers the types [policy] dependency-types governs, so policy = "banned" for a dependency does not reach its peerDependencies unless the group names peer. Bun reads overrides and resolutions of the root package.json, but ignores resolutions whenever overrides is present, even an empty {} (checked with Bun 1.4); skif still reads both, so in a Bun workspace keep the entries in one of the two.

override-reading chooses how those entries are read. "skif" (the default) is described above. "syncpack" reads them as syncpack 15 does: the key of an entry is the dependency name (parent@4>child and react@<18 are dependencies of their own, never aligned with child or react), only string values count (a nested npm object is skipped), and pnpm-overrides is the overrides of pnpm-workspace.yaml only, so pnpm.overrides of a package.json is not read. skif migrate writes "syncpack" when it migrates syncpack, so a clean syncpack run stays clean.

The first matching group wins. Selectors accept ! negation, and $LOCAL selects dependencies that are themselves workspace packages.

Key Meaning
label Optional name shown in diagnostics.
dependencies, packages, dependency-types, specifier-types Selectors.
policy preferred-semver (default), pinned, banned, ignored, same-range, same-minor, snapped-to or semver-range-only (syncpack’s semverRangeOnly: versions may differ, and only the range the [[semver-groups]] require is checked and fixed).
pin Required by pinned.
snap-to Required by snapped-to: packages whose version the group follows.
prefer With preferred-semver, overrides [policy] prefer.
scope manifests (default) judges what the manifests declare; lockfile judges every package pnpm-lock.yaml (bun.lock in a Bun workspace) resolves, transitive ones included. Only with banned.
[[version-groups]]
label = "Pin react"
dependencies = ["react", "react-dom"]
policy = "pinned"
pin = "19.1.0"
[[version-groups]]
label = "No moment"
dependencies = ["moment"]
policy = "banned"
[[version-groups]]
label = "No copyleft, not even transitively"
dependencies = ["left-pad"]
policy = "banned"
scope = "lockfile"

A path specifier (link:, file:, portal:, ./, ../, / or ~/) is never rewritten to a version and never the version others align with. In a dependency section, while local-path-dependency is on, it takes no part in any version group: that rule reports it, and its fix is the only one the entry gets. With that rule off, and in an override section or a custom type (which that rule does not read), a path keeps its version-group state without a fix: next to a workspace package’s own version, a path that resolves to the package is valid and one to another directory is a version-mismatch. banned groups report a path in every case.

A scope = "lockfile" group reports each resolved name@version it bans once, at its entry in the lockfile, with the shortest chain an importer pulls it in through (importer packages/app pulls it in through mid@2.0.0 > left-pad@1.3.0), so removing the overrides entry that kept a package out fails the lint. packages chooses the importers by the workspace package they belong to; dependency-types and specifier-types select manifest entries and are rejected. The group claims no manifest entry: those fall through to the groups after it. The lockfile is pnpm-lock.yaml in lockfile format 9 (pnpm 9 to 12), or bun.lock in a Bun workspace. Without it, with yarn.lock, package-lock.json or only Bun’s binary bun.lockb instead, or when it does not parse, banned-dependency reports that nothing was checked rather than passing.

[[semver-groups]]
label = "Libraries use caret ranges"
packages = ["packages/*"]
range = "^" # "" (exact) or one of * ^ ~ > >= < <=
[[semver-groups]]
label = "No range for type packages"
dependencies = ["@types/*"]
ignored = true # no range requirement; later groups do not apply (syncpack isIgnored / isDisabled)

A group sets exactly one of range and ignored = true.

A field of package.json that holds versions. Name it in a dependency-types list to select its instances; they are aligned, pinned, banned and ranged like dependencies, and fixed in place (syncpack’s customTypes).

[[custom-types]]
name = "node" # the token for dependency-types; the dependency name with strategy "version"
path = "engines.node" # dotted path of keys in package.json
strategy = "version" # version | name@version | versions-by-name | name~version
[[custom-types]]
name = "package-manager"
path = "packageManager" # "pnpm@9.15.0": the dependency is pnpm
strategy = "name@version"
[[custom-types]]
name = "runtime"
path = "volta.toolVersion" # the version
name-path = "volta.tool" # the dependency name, read from another field
strategy = "name~version"
[policy]
dependency-types = ["prod", "dev", "node", "package-manager", "runtime"]

versions-by-name reads an object of name: version. name~version reads the version at path and the dependency name at name-path, which only this strategy takes; a fix rewrites the version. A name must not be one of the built-in types. syncpack’s source (a custom type read from another file) is not supported.

[catalog]
mode = "prefer" # off | prefer | enforce
min-packages = 2 # packages using a dependency before an entry is suggested
exclude = ["typescript"]
report-unused-entries = true # default false: `unused-catalog-entries` reports nothing unless this is set

A [[version-groups]] entry whose selectors match a dependency claims it, whatever its policy: the catalog rules (catalog-not-used, catalog-mismatch, catalog-missing-entry, unresolved-catalog-references) leave it to the group, as syncpack’s first-match-wins order does. A pinned group for one package (a “baseline”) keeps that package off the catalog while the rest use catalog:, an ignored group exempts what it matches from the catalog rules, and a banned dependency is reported only as banned. Instances a group claims do not count toward min-packages, and the entry created for a missing dependency takes its version from the instances no group claims. A catalog: reference a group claims still counts as a use for unused-catalog-entries. catalog-mismatch reports only with mode = "off" and is a warning by default. Semver groups only choose a range and do not claim an instance.

[workspace-protocol]
internal = true # require workspace: for dependencies on workspace packages
allow-local-paths = false # accept file:/link: paths for internal dependencies

The rule is silent for npm and Yarn Classic workspaces, which cannot install the protocol, and for peerDependencies, which a published library names by range. While local-path-dependency is on, file:/link: paths are left to that rule so one dependency is not reported twice; allow-local-paths only decides them when local-path-dependency is off.

[[dependency-families]]
name = "babel"
packages = ["@babel/*"]
[[dependency-families]]
name = "react"
enabled = false # disable a built-in family of the same name
[[dependency-families]]
name = "playwright" # replaces the built-in family
packages = ["playwright", "playwright-core", "@playwright/test", "@playwright/browser-*"]
scope = "importer" # manifests (default) | importer | lockfile
[[dependency-families]]
name = "react-types"
packages = ["@types/react", "@types/react-dom"]
scope = "lockfile"
anchor = "react" # one version of each member per major of react

In the default manifests scope the members a package declares must share a version. scope = "importer" and scope = "lockfile" judge what the lockfile (pnpm-lock.yaml, or bun.lock in a Bun workspace) resolves instead, transitive packages included: per importer (what each workspace package reaches, not following link: to other workspace packages) or across the lockfile. Every resolved member must then be on one version; the lower ones are reported at their lockfile entry. With an anchor, each member may resolve once per major (@types/react 17 and 18 next to react 17 and 18), and a member on a major the anchor does not resolve to is reported. No member is exempt in these scopes (the manifests scope skips 0.x members of a released family and floating specifiers). The lockfile is read as for the version groups, and a missing, foreign or unparseable one is reported.

Read only by skif update, the one command that asks a package registry (CLI); linting never does.

[update]
minimum-release-age = 1440 # minutes a version must have been published before it is proposed; 0 turns it off
max-concurrent-requests = 12 # registry requests at once, at least 1

Without minimum-release-age, pnpm’s minimumReleaseAge from pnpm-workspace.yaml applies, else one day, as in syncpack. While a minimum release age applies, a version the registry gives no publish time for is not proposed, and the report notes it when it would have been the target.

[[update-groups]]
label = "React moves within its major"
dependencies = ["react", "react-dom"]
target = "minor" # latest | minor | patch
[[update-groups]]
dependencies = ["@types/node"]
ignored = true # skif update leaves these alone

The first matching group decides (syncpack’s updateGroups); a group sets exactly one of target and ignored = true, and its target combines with --target so the stricter wins. The selectors are those of [[semver-groups]]. A catalog entry belongs to no package and has no dependency type, so only groups without packages and dependency-types apply to it.

What the package-json-format rule and skif format check. The rule is off by default; the table is root-scoped and cannot appear in [[overrides]]. The defaults are syncpack’s, except sort-exports.

[format]
sort-first = ["name", "description", "version", "author"] # top-level keys that come first, in this order
sort-packages = true # the remaining top-level keys in byte order; false keeps their order
sort-az = ["bin", "contributors", "dependencies", "devDependencies", "keywords", "peerDependencies", "resolutions", "scripts"]
sort-exports = ["types", "default"] # types first, default last, every other condition where it is
format-bugs = false # { "url": "..." } becomes "..."
format-repository = false # { "type": "git", "url": "git+https://github.com/o/r.git" } becomes "o/r.git"
# indent = " " # unset: keep each file's layout

sort-az sorts each named field one level deep: an object by key, an array of strings by value; a/b names a nested field. It is for fields whose order means nothing: an array with a !-prefixed entry, such as files with a negated glob, keeps its order, because a negation only excludes what the patterns before it matched. sort-exports orders the keys of every object in exports (the others keep their order) and always puts default last. Node and bundlers take the first condition that matches, so only types first and default last cannot change how an import resolves; that is the default, and its fix is safe. A list that reorders other conditions, such as syncpack’s default ["types", "node-addons", "node", "browser", "module", "import", "require", "svelte", "development", "production", "script", "default"], is applied with an unsafe fix (skif format --unsafe, skif --fix-unsafe). format-bugs and format-repository collapse only an object the shorthand holds completely: a bugs with an email, or a repository with a directory or a type other than git (svn, hg), stays. An empty list turns its step off. Sorting is by byte order, the order unsorted-dependencies uses.

Without indent, formatting moves members with their own text and keeps every file’s whitespace, and whitespace is never reported. An object or array with a comment between its members is not reordered, and a bugs or repository with a comment inside is not collapsed, so a comment never ends up beside another member or disappears. With indent (spaces or tabs; "\\t" is read as a tab), a manifest must be laid out as JSON.stringify(manifest, null, indent) lays it out, with the file’s own line ending and a final newline. A manifest that is not strict JSON (comments, trailing commas, single-quoted strings) keeps its layout, because laying it out again would drop its comments or write invalid JSON. Only package.json files are formatted.

[js]
enabled = true
entry = ["src/index.ts", "src/server.ts!"]
project = ["src/**/*.ts"]
ignore = ["**/*.generated.ts"]
ignore-files = ["scripts/one-off/**"]
ignore-dependencies = ["@types/node", "/^@org\\/.+$/"]
ignore-binaries = ["docker"]
ignore-global-binaries = true
ignore-unresolved = ["#internal/*", "/^virtual:/"]
ignore-workspaces = ["tools/*"]
ignore-members = ["/^_/"]
ignore-exports-used-in-file = { type = true, interface = true }
production = false
isolate-workspaces = false
strict = false
include-entry-exports = false
tsconfig = "tsconfig.app.json"
use-tsconfig-files = false
include-fixtures = false
use-public-hoisting = false
discovery = "auto"
[js.cycles]
allow = [["src/a.ts", "src/b.ts"]]
dynamic-imports = false
[js.workspaces."."]
ignore-dependencies = ["rimraf"]
[js.workspaces."packages/web"]
entry = ["src/main.tsx"]
ignore-unresolved = ["virtual:*"]
include-entry-exports = true
paths = { "@/*" = ["./src/*"] }
[js.workspaces."packages/web".plugins]
vite = { config = ["vite.web.config.ts"] }
[js.plugins]
vitest = true
jest = { enabled = true, config = ["jest.config.cjs"] }
[js.compilers]
html = { imports = ['<script[^>]+src="([^"]+)"'] }
page = { as = "mdx" }

enabled defaults to true, so a plain skif run checks everything; the git hooks pass --no-js. Per-workspace tables, keyed by directory (a glob such as packages/* works, an exact key wins over a glob, and "." is the root workspace; * stops at /, so packages/* does not select packages/a/nested, and when several glob keys select a directory the first in file order wins), take entry, project, ignore, ignore-files, ignore-dependencies, ignore-binaries, ignore-unresolved, ignore-members, ignore-exports-used-in-file, include-entry-exports, paths and plugins, plus extend-ignore, extend-ignore-dependencies, extend-ignore-binaries and extend-ignore-unresolved, which append to the list the table inherits through extends. A plugin entry is true, false or a table with enabled, config, entry and project; the plugin names are checked, and a misspelt one is a configuration error with the closest name suggested. The "." table adds to the top-level ignore lists and replaces its entry and project.

The key type-aware was removed in 0.9.0 with type-aware analysis. In [js], a [js.workspaces."<dir>"] table or the js table of an [[overrides]] entry it is a configuration error that says so, names the file, line and column and exits 2; delete the key.

Ignore lists. ignore-dependencies, ignore-binaries, ignore-unresolved, ignore-members and ignore-workspaces take exact names, globs (@types/*) and regular expressions. An entry is a regular expression when it is written between slashes with optional flags (/^@org\/.+$/, /^vite/i), or, as in knip, when it contains +, \, (, ), | or ^, contains .* or .+, or ends in $. A regular expression is not anchored and matches anywhere in the name. This differs from knip, which also treats * and { as regular expression syntax; skif keeps them for globs so that @types/* means what it says, and an entry such as eslint-* is a prefix glob here but a regular expression in knip (where it also matches my-eslint-x). Regular expressions are compiled by the Rust regex engine, not by JavaScript: look-ahead, look-behind and back-references (/^(?!@types)/) are configuration errors, \d and \w are Unicode aware, and the flags i, m and s apply while g, u, y and d are accepted and ignored. skif migrate copies a knip pattern as written, so run skif once afterwards: an unsupported pattern is reported with the compiler’s message. A pattern that does not compile is a configuration error. An entry ending in ! applies in production mode only ("left!").

Reasons on ignore entries. Every ignore list (ignore-files, ignore-dependencies, ignore-binaries, ignore-unresolved, ignore-members, ignore-workspaces and the extend- keys, at the top level, in [js.workspaces."<dir>"] and in the js of an override) takes an inline table in place of a string, so the entry records why it exists:

[js.workspaces."packages/app"]
ignore-dependencies = [
"left-pad",
{ name = "some-loader", reason = "false positive: loaded by the bundler from a config string" },
]

name holds what the string form holds (a name, a glob or a slash-delimited regular expression, with the ! production marker), and reason is optional. The two forms mix in one list and match the same. A blank reason is a configuration error, and --require-ignore-reasons or [lint] require-ignore-reasons fails a run on an entry without one. stale-js-config reports a table entry that matched nothing by its name.

ignore-unresolved lists import specifiers that are never reported by unresolved-imports or stale-mocks, at the top level and per workspace. ignore-dependencies also silences both for a matching specifier, because plugins declare virtual modules through it; use ignore-unresolved for your own. Two small differences from knip remain: an unresolved import is located at the start of its statement, not at the specifier, and import "./dir" of a directory with neither an index file nor a package.json is reported where knip is silent. A directory with a package.json whose main or exports point at build output that does not exist resolves to the source file behind it (dist to src), and is not reported when there is none. So does a relative import into a package’s own build output that was never built (require('./dist/client/link') in a file the package publishes beside dist): it resolves to the source that output is built from, through the package’s outDir and rootDir or from dist to src, unless the importing file lies in that output directory itself. A relative import of a missing file that a .gitignore lists (also as ./dir for an ignored dir/index.ts, or without its extension) is taken for generated and not reported: the .gitignore of the root, of a package, or of any directory between the file and the git repository root, such as a src/temp/.gitignore that ignores its own contents or the .gitignore of a folder above a nested root. The same holds for a tsconfig paths entry or a bundler alias whose target is such a path, whatever the specifier is named like: "electron": ["../.build/typings/electron.d.ts"] with .build/ ignored makes electron neither unresolved nor unlisted. So is one that names an ignored path below another rootDirs directory of the nearest tsconfig.json that is not generated yet (./+types/root of a React Router route, from .react-router/types), SvelteKit’s ./$types while the .svelte-kit/tsconfig.json that the nearest tsconfig.json or jsconfig.json extends, directly or through another config, is missing and gitignored (once svelte-kit sync has written it, its rootDirs decide: a route type is not reported while the ignored .svelte-kit/types is missing too, and is reported once that directory exists without it), a root-relative import of a JSON or other non-code file (import logo from "/vite.svg", served from the bundler’s public directory), and a # specifier unless the nearest package.json declares imports. Since the generated module may import any source file beside it, those files are reached and their exports count as used: the files of the ignored file’s directory, of an ignored directory and below it, or, for the ignored index of a directory (src/migrations/sqlite/index.ts named as ./migrations/sqlite), of the directory holding that directory and below it (src/migrations/**), within the importing package. When those files would be the package directory or its src (an ignored src/schema.gen.ts, or src/generated/index.ts named as ./generated), none are credited, since that would hide most of the package’s unused files.

A require() or import() of a template literal with a relative static prefix (import(`./reporters/${name}.js`)) reaches every file matching the prefix, * for each substitution, and the suffix, as import.meta.glob does, and their exports count as used; an output extension also matches the sources it is built from (.js matches .ts and .tsx). A last segment without an extension names a module as a specifier does: a file with any code extension, or the index of a directory (require(`./commands/${name}`) reaches commands/login.js and commands/trust/index.js, and require(`./locales/${lang}/messages`) reaches locales/en/messages.js). A const that holds a path built from the file’s directory (const entry = path.resolve(__dirname, "cli/entry.js"), also path.join, require("node:path").resolve and string literals after __dirname) names its module where a require(), import() or require.resolve() of the same file reads it by name, also inside a nested function; a parameter or local of the same name, a let and a computed segment are not followed. Paths built at runtime in other ways are not followed: another specifier held in a variable, a fast-glob or glob call listing files relative to __dirname, or a registry that loads ${name}/${name}.module.js from a directory it computes. Add such files to entry.

ignore-workspaces lists workspace directories (globs) the JavaScript analysis skips. Unlike [workspace] ignore-packages, the packages stay in the workspace, so manifest and policy rules still check them. The root is never skipped. Entries match directories, so * stops at /: packages/* skips packages/a but not packages/a/nested (use packages/** for both), as in knip. A matched directory also leaves the packages above it: the files below it that belong to no skipped member (playground/demo/loose.js with playground/**) are not analysed in the root or any other package, as in knip.

[js.compilers] reads the files of an extension skif has no reader for, keyed by the extension without its dot. It is the static counterpart of knip’s compilers: knip runs a function that turns the file into JavaScript, skif runs no project code and takes one of two declarations instead.

  • imports: regular expressions, each with exactly one capture group, matched against the whole text of the file. Every capture is an import specifier, resolved as an import written in that file (./src/main.ts from the file’s directory, lit as a package), so a missing file is reported by unresolved-imports and a package the manifest does not list by unlisted-dependencies. The imports bring in no names, like import "./x". The patterns are compiled by the Rust regex engine (no look-around or back-references); (?:...) groups do not count as capture groups.
  • as: read the files with the reader of one of skif’s own extensions, as if they had it: js, mjs, cjs, jsx, ts, mts, cts, tsx, vue, svelte, astro, mdx, marko, tsrx, or a stylesheet extension (css, scss, sass, less, pcss, styl, stylus).

The files of a declared extension join the default project (**/*.html), so one that no entry reaches is reported by unused-files; a project that leaves the extension out leaves them unjudged. They are modules for every other purpose too: an import of one (import "./intro.page") follows it, and project-extension-unregistered does not report the extension. A file that only a tool loads, such as an index.html no bundler plugin reads, needs an entry pattern. A declaration for an extension skif reads itself (vue), an extension written with its dot or in upper case, an entry with both or neither of as and imports, an unknown reader, an empty imports list and a pattern that does not compile or has not exactly one capture group are configuration errors. The table applies to the whole root: it cannot be set per workspace or in an override, and a nearer configuration file replaces an extension’s entry as a whole.

[js.compilers]
# <script type="module" src="./src/main.ts"></script>
html = { imports = ['<script[^>]+src="([^"]+)"'] }
# Tailwind directives in a stylesheet extension skif does not know
tw = { as = "css" }

entry and project. As in knip, a pattern ending in ! is a normal pattern in a normal run. In a production run only the patterns ending in ! count and the others are excluded; when none ends in !, the defaults apply. The entries that do not end in ! are also removed from the project, so a file only they reach (scripts/*.ts next to src/index.ts!) is not reported as unused, and the files that tools add to the project are removed as well, as are the development entries of plugins (stories, test files, Vitest setupFiles): they are no production code. A plain pattern that matches what a pattern ending in ! selects (src/main.js or src/** next to src/main.js!) therefore excludes the files from a production run, which stale-js-config reports. The exclusions made of the plain patterns apply to the patterns of the configuration only, as in knip: a file that a plugin names as a production entry (the src/mastra/index.ts of Mastra, an entry of a tsup.config.ts) stays a production entry when a plain pattern matches it too. A !src/mastra/index.ts pattern still removes it, as it does in a normal run.

Incomplete entries. When skif cannot know all the entry files of a package (a tool configuration it cannot read statically, a published main, exports or bin that maps to no source file, or a tool’s entry in build output that maps to no source file), a file no known entry reaches may still be one. A tool’s entry that names one file that does not exist (a bundler’s lib-esm/entry.js) stands for its source as a published path does: through the outDir and rootDir of a tsconfig, then from a build output directory to its src twin, with .js mapping to .ts and .tsx. One in build output with no source behind it leaves the package incomplete (unmapped-entry). A published path that names nothing at all (no file, no source behind it, not in a build output directory, not ignored by git and not in a bin directory a build step of the package may write, such as a stale bin/cli.js) is not one of them: it is no entry, stale-js-config reports it (package-entry) and the package is judged from its other entries. unused-dependencies and unused-dev-dependencies then skip the package: an unread configuration may name a package by string (a test environment, a coverage provider, a reporter). unused-exports, unused-types, the namespace export rules and the member rules skip the files that may be unknown entries: the whole package, or only the files of the narrowed scope described below, and explain-usage gives their exports the verdict not-judged.

unused-files skips only the files the unreadable configuration could plausibly make entries, its narrowed scope. A config that is unknown, spreads or merges in an unknown base, or computes its entry keys can only add entries where its tool looks for them. A method or function value of a config that changes or spreads the value a call gives it and returns it (a bundler hook such as Storybook’s viteFinal, webpackFinal and rsbuildFinal, or Next.js’s webpack) leaves the rest of the config known:

Plugin Narrowed scope (relative to the package, besides the plugin’s own entry globs)
next {,src/}{app,pages}/** and {,src/}{instrumentation,instrumentation-client,middleware,proxy}.*: the router may take other extensions there
vite {,src/}{index,main}.*, the conventional build input a shared base config may set
vitest, playwright test files, test and fixture directories (test, tests, __tests__, __mocks__, __fixtures__, e2e, spec, specs, fixtures, mocks, testing, test-utils), files whose name contains setup or teardown, and files named *.{test,spec,bench,e2e,integration}*
storybook for an addon, framework or core.builder whose package is not known statically, the Storybook config directory (.storybook/**, .rnstorybook/**), where a local addon lives; the package’s dependencies are not judged

A config in an Nx project directory without a package.json (see Nx workspaces) hides entries only in that project: the scope above is taken relative to the project, and a config that gives no scope leaves the project’s files unjudged (<project>/**) rather than the whole package’s. Nx’s root jest.config.ts (projects: await getJestProjectsAsync(), or getJestProjects(), from @nx/jest or @nrwl/jest) is not incomplete: its projects are the Jest configs of the Nx projects.

The files in the scope are treated as entries, so what they import is not reported either: those outside the package’s project globs too, and, for a scope of a package with workspace packages below it (a root test config), the matching files of those packages. Every other file of the package is judged as usual, its unused exports, types and members included, since whatever an unknown entry in the scope imports is already counted. The exports of a file in the scope are not judged, even with include-entry-exports, as the tool may read them. The whole package stays unjudged when the configuration does not parse (an esbuild build script that exports nothing is read for every entryPoints it writes, and counts as unparsable only when it writes none), when a vite config computes root, build.rolldownOptions.input (Vite 8), build.rollupOptions.input or build.lib.entry itself or is unknown as a whole (a key is computed by the config itself when an unknown spread inside it, or above it of a value the config computes, such as build: { ...makeLib() } with makeLib declared in the config, may set it; a spread of an imported base is shared and narrows), when a vitest config computes root, test.include, test.setupFiles, test.globalSetup or a test.reporters name itself or is unknown as a whole, when a playwright config is unknown as a whole or computes its reporter list itself (a reporter’s name is not known statically, or a spread of a value the config computes may set the list: a reporter module may be any file; a reporter a condition picks among known ones, process.env.CI ? 'github' : './reporter.ts', credits each), when a storybook config is unknown as a whole, spreads an unknown value or lists stories not known statically (stories: [...shared]), when the plugin gives no scope (any other plugin), when the published build output maps to no source file (publishing may expose any file), and when a module of the package imports a computed path (import(name), require(name)), which may load any of its files. explain-usage says which applies: a file in the scope is an entry of kind incomplete-scope, a file outside it reported by unused-files names the scope, and a file of a package left unjudged as a whole is entries-incomplete.

A file that a relative import reaches through the rootDirs of the importer’s tsconfig.json (code generated into a build output tree such as bazel-bin/packages/app) belongs to the importing file’s package when it lies in no workspace package’s directory and is not a source file skif lists (build output that git ignores), and so do such files it imports by relative paths below the same root directory: their imports are judged against that package’s dependencies, which Node.js resolves them from. A file of a workspace package always stays that package’s, and the root’s ignore globs still apply to an adopted file.

In a Bazel repository (the nearest directory at or above the workspace root, within the git repository, with a MODULE.bazel, REPO.bazel, WORKSPACE.bazel or WORKSPACE), the output trees behind the bazel-* links at its top (bazel-bin, bazel-out, bazel-testlogs, bazel-<workspace>) are never read: their contents are whatever the last build left, for whichever configuration. An import that reaches a file there, through rootDirs or otherwise, is of generated code and is not followed, so no finding is located in them. A relative import of a missing file is not reported when the nearest BUILD.bazel or BUILD file at or above the file’s directory declares it as an output: it is a literal of the outs, out or stdout of a target there (js_run_binary(outs = ["src/gen/schema.js"])), also with another extension or none, or lies below one of its out_dirs or out_dir. Bazel builds it into bazel-bin beside the package. A rootDirs directory below bazel-bin does not make a missing import generated, built or not; the BUILD files decide, so an import that none declares is unresolved whatever was built. The dependencies of the generated code are those its target names (see the bazel plugin below).

paths is a tsconfig-style map for one workspace, { "alias/*" = ["./target/*"] }, targets relative to the workspace directory, matched as TypeScript matches compilerOptions.paths. A key without * matches only that specifier; a key may hold one * anywhere ("*", "serv*", "*.svg", "alias/*"), which matches any text, and the target’s * takes the text it matched. The keys that match are tried by the length of the text before their *, longest first, and a key without * before every wildcard, each with its targets in order. Relative and absolute specifiers are never mapped. A key or target with more than one * is a configuration error. The patterns are tried ahead of the aliases tools declare, the paths of the workspace’s tsconfig.json or jsconfig.json included, and, as TypeScript tries compilerOptions.paths, ahead of baseUrl, installed packages and workspace members: "src/*" = ["./src/*"] beside a member or an installed package named src reaches the workspace’s own src/ files. A key whose targets are all missing falls through to the package. knip tries the package first and reports the local file as unused. A target in a workspace package’s build output (an outDir it declares, or an ignored path such as ../lib/dist/index.js) stands for the source that output is built from, whether or not it was built; this holds for these aliases, tsconfig paths and bundler aliases.

tsconfig names the TypeScript configuration of the root package, relative to the workspace root, which is read in place of its tsconfig.json: its paths, baseUrl and rootDirs resolve the imports of the root package’s files (and of directories below the root that have no config of their own), its compilerOptions decide which @types packages and JSX runtime count as used, and the typescript plugin reads it too. Other packages keep their own tsconfig.json. The path must stay inside the workspace root (no absolute path, no .. above it), and the command line refuses a path that names no file in the root whose configuration sets it. This is knip’s --tsConfig, which skif --tsconfig overrides. It can only be set at the top level.

use-tsconfig-files takes the project files of each package that has a tsconfig.json (for the root, the tsconfig above) from it, as knip’s --use-tsconfig-files does: the files its files and include select (every file when it sets neither), followed through extends and through the references that lie below it. As in TypeScript, exclude and compilerOptions.outDir filter only what include selects, never the files files names. These replace the project globs and the globs plugins add; entry files are unchanged, and production mode still leaves test files out. Patterns that leave the package directory are ignored, and the exclude of a referenced config applies to what the include of all of them selects. Packages without a tsconfig.json keep their project globs. The command line warns on stderr about a tsconfig that selects no file of its package, which leaves that package without project files.

ignore-exports-used-in-file is true, or a table of the kinds variable, function, class, enum, namespace, type and interface: an export that the same file references is then not reported. The export clause itself (export { x }, export { x as y }) and the object of module.exports = { x } are no reference; a read of x anywhere else is, whether x is a local declaration or an import binding the file re-exports (import a from "./a"; export { a }; export default { a }). An import binding counts only where it is read as a value, not in a type position. Only true exempts a re-exported import binding: it has no kind of its own. An export initialised from a used binding (export const b = a) is not referenced itself. skif does not tell type aliases from interfaces, so type and interface are the same switch. member is accepted; members read in their own file always count as used. ignore-members lists enum, namespace and class member names never reported by unused-enum-members, unused-namespace-members and unused-class-members, as knip’s ignoreMembers does. A member is also exempt when its own JSDoc carries a tag that exempts an export (@public, @beta, @alpha, @alias, @internal with production, or an ignore-tags name). include-entry-exports may be set per workspace.

unused-class-members (a warning) reports the methods, fields and accessors of a used exported class that no module reads, like knip 5’s classMembers (knip 6 dropped the issue type). skif has no type checker (ADR 0010): a member counts as read when any module of the graph reads a property of its name on any object: x.name, x?.name, x['name'], a destructured key, this.name, super.name, a string literal type or call argument (vi.spyOn(x, 'name')), and every .name in the markup of a component file. An unused member whose name another class’s member shares is therefore not reported when that name is read. An element access whose key is a constant reads the string the constant holds: x[KEY] with const KEY = '__v_skip', x[Flags.SKIP] with enum Flags { SKIP = '__v_skip' } or const Flags = { SKIP: '__v_skip' } as const, declared in the same module or imported (also through a namespace import or a barrel); a let, a plain object’s property or a parameter can hold any key and reads nothing. A field that is only assigned (x.name = 1) is unused, a setter is used when it is assigned. The constructor, private members and members with a computed key ([Symbol.iterator]) are not judged, and nor are a field that exists only for the type checker (a declare field, or a brand typed void, never, undefined or unique symbol with no value but undefined, such as readonly __brand!: unique symbol), a decorated member, every member of a decorated class (@Component()), members of an interface the class implements (all of its instance members when the interface is not declared in the same file), the members a known library base class declares (React’s render and lifecycle methods), every member of a class whose superclass chain leaves the project for another class (extends HTMLElement, a mixin call, a class of an installed package), and the classes an entry file exports, which are public API unless include-entry-exports is set. A default-exported class is judged like a named one, through a default import, ns.default or a re-export as default; a class exported under several names (export class C beside export default C) is judged and reported once, and is public API when an entry file exposes any of them, also through export default of an import. A finding names a default-exported class by its declaration (Foo of export default class Foo), or default when it is anonymous. skif explain-usage FILE#Class.member shows the files that read a property of that name on any object, or why the member is not judged. For FILE#Enum.member and FILE#Namespace.member it says whether the member is read through an import or in its own file, or the whole enum or namespace is used.

ignore-files lists globs of files that unused-files never reports, at the top level (relative to the workspace root) and per workspace (relative to its directory), like knip’s ignoreFiles. Unlike ignore, every other rule still analyses them.

[js.cycles] configures circular-imports (off by default), like knip’s cycles. allow lists cycles that are not reported, each as the list of its files relative to the workspace root (./ is optional): skif reports a cycle as the set of modules that import each other, so an entry allows the cycle whose files are exactly its files, in any order; an empty entry or an empty path is a configuration error. dynamic-imports = true counts import() as an edge; by default only static value imports do, and type-only imports and resolve calls (require.resolve, import.meta.resolve), which load nothing, never do.

stale-js-config (a warning) reports ignore-dependencies, ignore-binaries, ignore-unresolved and ignore-workspaces entries that matched nothing in the run, [js.workspaces] keys that select no package, and entry, project and ignore patterns (top level and per workspace) that match no file, like knip’s configuration hints (entry-empty, project-empty and stale ignore). A pattern is reported only when it matches neither a file the analysis knows nor any file on disk, gitignored or not and of any extension, so ignore = ["dist/**"], ignore = ["**/*.json"] and entry = ["index.html"] are not reported while such files exist; the disk check skips node_modules and .git unless the pattern names them. A pattern of a workspace glob key such as packages/* is reported once, under the key as written, when it matches in none of the packages the key selects. Negated patterns and patterns that leave the package (../) are not judged. An ignore-files pattern is reported when it hides no file unused-files would report and matches no file on disk (while that rule runs). [rules] stale-js-config = "error" is knip’s --treat-config-hints-as-errors (skif migrate writes warn unless --strict-hints is given). An ignore-dependencies or ignore-unresolved entry is not judged when a rule that consults it is off. The ignore-dependencies list of a package whose entry files skif cannot determine is not judged; the global list is judged over the other packages, and an entry that matches a dependency such a package lists is never called stale. In a multi-root run, a finding about a configuration file several roots read (a --config file, or a file above them) is reported once, at the highest severity among the copies the run shows, and an entry of its lists only when every root that judged it found it stale: a root that used it silences it, and a root that could not judge it (a rule off, entry files it cannot determine) has no say. Each package a [js.workspaces] glob table selects has a list of its own, so one package’s use of an entry does not silence it for another. The decision is made over what the run shows, after --fix and after --workspace, --include and --exclude: a copy those flags leave out of the run does not raise the severity of the one reported. It also reports knip’s tag hints: an ignore-tags tag, or @internal with production, on an export or member that is used anyway (while unused-exports runs). A tag on an enum or namespace that hides an unused member is needed and not reported. The tag hints cover the files whose exports unused-exports judges, so in a package with incomplete entries narrowed to a scope they cover every file outside it.

The rest of knip’s configuration hints are part of stale-js-config too:

  • entry-redundant: an entry pattern that is a plain path to a file a plugin, the manifest (main, exports, bin, …), a tool configuration or a script already makes an entry. With include-entry-exports, only plugin entry globs and the manifest count, since a configured entry has its exports judged.
  • project-redundant: a project pattern that is a plain path to an entry file, which is always in the project. Not judged with use-tsconfig-files.
  • entry-top-level and project-top-level: the top-level entry or project in a workspace with several packages, where they apply to the root package only; move them to the [js.workspaces] table they are meant for.
  • project-extension-unregistered: a project pattern selecting an extension skif does not analyse (*.json). Stylesheets (.css, .scss, .sass, .less, .pcss, .styl, .stylus) are not reported: skif reads their imports, so a knip project glob such as src/**/*.{ts,css} keeps working unchanged. Neither are the extensions of [js.compilers]. project-extension-excluded: project patterns that name extensions but not .vue, .svelte or .astro while the package has such files, which then leave the project. knip ties both to its compilers; skif reads those component files without one, so the second is judged by the files present instead.
  • package-entry: a path in main, module, browser, bin, types, typings or exports that names no file, neither itself nor a source file behind it. Paths a .gitignore hides, paths in a build output directory (dist, build, lib, …, whatever the extension; knip reports these unless gitignored) and paths into a listed dependency are not judged. It points at the field in package.json. A path in a bin directory in any published field ("bin": "bin/cli.js", but also "main": "bin/cli.js") that names no file is reported too, and since it loads no code it does not make the package’s entries incomplete; a root "bin": "cli.js" was always reported, and a path in dist/... still is not. A bin path is not judged when a build step of the package may write it: a build, build:*, prepack or prepublishOnly script, a script that runs a compiler or bundler (tsc, tsup, tsdown, esbuild, rollup, rolldown, webpack, rspack, rslib, unbuild, ncc, babel, swc), a bundler configuration a plugin reads (tsup.config.ts, rollup.config.mjs, …), or a tsconfig outDir at or inside bin. When the only build steps run the TypeScript compiler (tsc, tsgo, without --outFile), the path is judged unless a file of the package has its name (stack.ts for bin/stack.js), also when a .gitignore hides it (*.js): the compiler names each output after a source file, so a bin/stack.js no source is named after is a path into nothing. Ignored paths count with the ignore files from the root of the git work tree down, also above the analysed root, and .git/info/exclude; the global excludes file (core.excludesFile) is not read.
  • top-level-unconfigured and workspace-unconfigured: more than 20 unused files that are more than a fifth as many as the files the analysis reached suggest missing entries, with knip’s thresholds. A single-package workspace gets one hint; otherwise each package with more than one unused file gets one, largest first.

One hint has no knip counterpart: a plain entry or project pattern that cancels a pattern ending in ! of the same list ([js] or a [js.workspaces] table). A ! pattern naming one file is cancelled by every plain pattern that matches the file (src/main.js or src/** next to src/main.js!); a ! glob only by the same glob (src/** next to src/**!), so a plain glob written differently (src/**/*.js next to src/**!) is not reported. Patterns are compared as skif compiles them, without surrounding whitespace or a leading ./. In a production run the plain pattern excludes what the ! one selects, so the files are left out instead of kept; in a normal run the ! pattern selects them on its own. Remove the plain pattern to keep the files in both modes, or the ! one if they are not production code. project patterns are not judged with use-tsconfig-files.

Where binaries are run. unlisted-binaries reads the commands of the package.json scripts, the commands that plugins read from the files of their tools (workflow steps of .github/workflows, Git hooks, lint-staged tasks and the other configs that hold commands) and the literal commands that source files reachable from an entry run through node:child_process (exec, execSync, spawn, spawnSync, execFile, execFileSync), execa, zx and nano-spawn. A binary of a script is reported at the script in package.json; one of any other command at the file that holds the command. A binary fetched on demand (npx x, pnpm dlx x) is never reported, and a command whose arguments are computed is not read. A specifier .bin/x, node_modules/.bin/x or ./node_modules/.bin/x, in require.resolve, import.meta.resolve or any other import, names the link of binary x, which code looks up to spawn it: it uses the dependency that provides x, whether or not it is installed, is reported at the file when no dependency provides x, and is never an unresolved-imports finding. The steps of CI workflows, Git hooks and task runners run on machines that bring their own tools, so a binary they run by name is never reported there; one they run through a package manager (pnpm exec x, yarn x) or a node_modules/.bin path is, as knip does. A GitHub Actions step whose shell is not a POSIX shell (pwsh, cmd, python) is not read. The binary of a workspace member is provided where the package manager puts it on the PATH: with npm, Yarn Classic, hoisted pnpm and hoisted Bun, which link every member’s binaries into the root node_modules/.bin, for every package; with isolated pnpm, npm with install-strategy=linked in the root .npmrc, Yarn Berry, isolated Bun and in a Rush repository only for the packages that list the member and for the member’s own scripts. pnpm is hoisted with nodeLinker: hoisted in pnpm-workspace.yaml, or without a nodeLinker there with node-linker=hoisted in the root .npmrc only before pnpm 11 (pnpm 11 reads its linker only from pnpm-workspace.yaml; without a pnpm version in packageManager, .npmrc is read). Bun is isolated with linker = "isolated" under [install] in the root bunfig.toml, or without a linker when bun.lock records configVersion 1. In a Rush repository (a rush.json at the root), rush, rushx and rush-pnpm are Rush’s own commands and never unlisted.

Scripts that change directory. A package.json script command after cd <dir> or pushd <dir> (until popd), and one that npm --prefix <dir> exec, pnpm -C <dir> exec (--dir) or yarn --cwd <dir> exec runs, runs in that directory: the files it names are relative to it, and when the directory is in another workspace package, the binaries it runs and the packages it loads are credited to that package, as for pnpm --filter <name>. A binary that package does not provide either is reported at the script, naming the package it runs in (script `a` runs `x` in `packages/web`, which no dependency of `web` provides), unless a package manager runs a script of that name there (cd web && pnpm bundle). When the directory is in a project of its own instead (a directory below the package with a package.json that is no workspace member, such as a nested root of skif -r), a binary run there is judged against that project’s manifest: a provider it lists is used, and skif -r credits it to that root; otherwise one of the package holding the project may provide it, else it is reported, naming the project. In a directory of the package itself or of no package or project, a command after cd stays a command of the script’s package and one a directory flag runs is not judged, as before. The binaries and packages that a workflow step, a tool config’s command or a source file run and load after cd <dir> (run: cd sub && pnpm exec rspack, run: cd sub && node -r hook x.js) are placed the same way, with the directory relative to the package where the command starts (the workspace root for a workflow), and are not credited where the command starts. A binary such a command runs by name where its tool does not judge one (a workflow step), or fetches on demand, is only a credit there. A step’s working-directory, its own or the defaults.run of its job or workflow, is read as a cd before the step. In a workflow step, $GITHUB_WORKSPACE, ${GITHUB_WORKSPACE} and ${{ github.workspace }} are the workspace root, so cd $GITHUB_WORKSPACE/sub and a working-directory of ${{ github.workspace }}/sub are followed. A script that a package manager runs in another directory (cd web && npm run build) is the script of the package there, so the caller’s script of that name is not followed. A cd in a subshell ((cd "$TMP" && tar xf a.tgz) && npm run build) ends with it. A command substitution runs in the directory of the command that holds it (cd sub && SUITE=$(pnpm exec tsx resolve.ts) runs tsx in sub), a command of redirections alone included (cd sub && > "$(tsx x.ts)"). A directory that is not a static relative path (cd $DIR, cd /tmp, cd -, cd "$(dirname "$0")") is not followed: a binary run by name there is judged where the script starts, but a package manager run there (npm run build, bun run build, pnpm exec rspack) works on the package of that directory, as with --filter, so its scripts are not followed and its binaries are not judged. A command that a source file runs with a cwd option (execa('bun', ['run', 'build'], { cwd }), execSync('npm run build', { cwd })) runs in such a directory, unless the cwd names the directory the call runs in anyway (process.cwd(), '.', undefined), which changes nothing, or the file’s own location computes it (__dirname, import.meta.dirname, path.join(__dirname, '../sub')), which runs the command in that directory below the file. knip judges these commands at the script’s own package.

ignore-global-binaries (default true, top level only) keeps unlisted-binaries quiet about the system and platform tools scripts run (rm, curl, git, docker), which are installed globally, like knip’s ignoreGlobalBinaries. The Bazel launchers bazel, bazelisk and ibazel and the claude CLI count as such tools too, while a listed @bazel/bazelisk, @bazel/ibazel or @anthropic-ai/claude-code is still used by the scripts that run them. Set it to false to report each one that no dependency provides, unless ignore-binaries lists it. Shell builtins (cd, echo, export), shells, pass-through commands (env, sudo, xargs), the package managers and node are never reported.

isolate-workspaces (default false, top level only) is workspace isolation: each workspace package uses only the dependencies its own package.json lists. An import, a binary a script runs, or a package a tool config names is no longer satisfied by a containing package or the root, so it is reported as unlisted in the package that uses it, and a root dependency only members use is unused. A private package’s import of a workspace member it does not list is reported too, and use-public-hoisting is ignored. Manifests above the analysed root still count. Isolation is independent of production: in the default mode tests, test setup, scripts and tool configs are checked against their own package’s manifest, development dependencies included, so one run checks every package against its own manifest. What counts as listed is unchanged: a type-only import or re-export (export type { T } from 'pkg') still needs a listing (a listed @types package stands in, and the finding names it as a fix besides the package), and a package’s own devDependencies satisfy any of its files. skif --isolate-workspaces sets it.

strict (default false, top level only) is knip’s strict mode, the configuration counterpart of skif --strict: production and isolate-workspaces, and only direct dependencies count. Production code must import from dependencies or peerDependencies, a peer dependency of a listed package no longer stands in for a listing, type-only imports use no package, and unused-dependencies also reports required peer dependencies nothing imports (see --strict in the CLI reference). With strict = true, production = false and isolate-workspaces = false have no effect.

use-public-hoisting (default false, top level only) counts a package that the install hoists publicly into a node_modules above a package as available to it, so a file that imports it without listing it is not reported by unlisted-dependencies. Off, skif reports such an import as knip does; ignore-dependencies (or --ignore-dependency) quiets one package instead. On, skif reads:

  • pnpm’s publicHoistPattern and shamefullyHoist from pnpm-workspace.yaml, else public-hoist-pattern and shamefully-hoist from the top level of the root .npmrc, which pnpm 11 no longer reads for these settings (so .npmrc is skipped when the root’s packageManager names pnpm 11 or later). The patterns hoist into the root node_modules, so they apply to every package. * matches any run of characters, a ! pattern excludes what the patterns before it include, and shamefully-hoist = true is the pattern *. Without a setting nothing is hoisted: pnpm’s default, which changed in pnpm 10, is not assumed. Rush repositories are not read.
  • public_hoist_packages of rules_js’s npm_translate_lock, in the Bazel repository root’s MODULE.bazel, WORKSPACE.bazel or WORKSPACE, when it is a dict literal: each key (a version suffix such as @1.2.3 dropped) is available to the packages at or below each Bazel package its list names, "" being the repository root.
[js]
use-public-hoisting = true

with public-hoist-pattern[]=hoisted-only in the root .npmrc, or npm_translate_lock(..., public_hoist_packages = {"hoisted-only": [""]}), makes import 'hoisted-only' in any package no unlisted dependency. The setting changes no unused-dependencies finding: a package a manifest lists is used or unused as before, whether it is hoisted or not. Workspace isolation (isolate-workspaces, and strict, which implies it) ignores it, since every package there uses only its own manifest. node-linker=hoisted and the flat layouts of npm, Yarn Classic and Bun are not counted: they make every installed package resolvable everywhere, so counting them would amount to turning unlisted-dependencies off. Binaries are not affected: a hoisted package’s binary is still credited only to a package that lists it.

discovery chooses how source files are found. auto (the default) and walk walk the directories, which finds every untracked file. git lists the files from the git index when the analysed root is in a git work tree and checks each directory with one stat instead of walking it: a directory modified at or after the time the index was written (equal counts as modified) is listed from disk, so new untracked files and directories, plugin config files that were never git added and deleted files are found and dropped as the walk finds and drops them, and an untouched directory is listed from the index without an opendir. One case is invisible to git: an untracked file created before the last rewrite of the index (a git add or git commit of another file, or a git status that refreshes it) in a directory nothing has touched since. That is why auto does not use the index: such a file is the entry or the only importer of a file that would then be reported as unused. git suits a fresh checkout, as in CI, and its unused-files findings offer no fix that deletes the file (ADR 0007). git falls back to the walk when there is no usable index: a repository outside git, a split or sparse index, a SHA-256 repository (extensions.objectformat), or an index whose SHA-1 checksum does not match (an index written with index.skipHash, which feature.manyFiles sets, is read without the check, so a torn read of an index that is being rewritten is then only caught by the reader’s bounds checks). A file the index lists but that is missing on disk is never reported. The .gitignore rules, hidden directories and [js] ignore apply to the listing as they apply to the walk. The rules that list directories for files workspace discovery does not read, the toolchain scan (version files, Dockerfiles, shell scripts, workflows and the files globs) and the search for the Bazel BUILD files of stray-lockfile, list through the same index listing under git, so they share its speed and its blind spot (ADR 0007).

A dependency counts as listed when the package’s own package.json, the package.json of a package that contains it, or any package.json above the analysed root up to the git repository root lists it; the same manifests enable plugins. With isolate-workspaces (or strict), a containing package no longer counts.

Packages tool configs name. A package that a tool config names itself is a dependency of the package whose directory holds the config: a tsconfig extends, compilerOptions.types or compilerOptions.plugins entry, an Oxlint jsPlugins entry, an ESLint plugin, parser or shareable config, a Babel preset or plugin, a PostCSS plugin, a Prisma generator provider, and what the other plugins read the same way, including a fixed name a plugin derives from a config value (importHelpers: true names tslib), as knip does. A listed one is used; one no manifest lists is reported by unlisted-dependencies at the config with the detail ConfigReference (“tsconfig.json references @acme/tsconfig, which is not listed in package.json”). Built-in names (prisma-client-js, a generator client block), relative paths and the string extends of an ESLint flat config (js/recommended) are no packages, except a relative path into a node_modules directory: an Oxlint extends of ./node_modules/ultracite/config/oxlint/core/.oxlintrc.json names ultracite, installed or not. Only a config of the workspace names a package this way: a config file an installed config extends in turn is that package’s dependency. A built-in ESLint config (eslint:recommended) is an optional reference to eslint; knip credits it as a plain dependency, which it reports where no manifest lists eslint, but skif does not, since a package that only enables ESLint may get it from the root. A package that a command in a config names (node --require x in a hook), one a plugin assumes without reading a config, and an optional reference (Vite’s optimizeDeps.include, an eslint-plugin-import resolver) is only a use and never reported. So is a package a config names only on a branch the environment chooses: one whose test reads process.env or import.meta.env, directly or through a top-level constant, and that the config cannot decide. A shared Vitest config that spreads coverage: { provider: 'v8' } only when process.env.COVERAGE_ENABLED === 'true' makes @vitest/coverage-v8 a use of each package that lists it, and unlisted in none. skif reads such a config with every test on the environment taken as true, then as false, and a package named in both readings, or under a test that reads something else (existsSync('.coverage')), is reported as before. A config that imports the package it names is reported once, for the import. What a config takes from a module of another workspace package (an imported shared config) is judged against that package, except a bundler alias replacement naming a package ({ find: 'stream', replacement: 'stream-browserify' } of Vite, Vitest, webpack or Next.js): the bundler resolves it from the files it bundles, so it is judged against the package whose config is read, however the alias is built.

A tsconfig compiler option (types, jsxImportSource, plugins, importHelpers) applies to each package that reads the config, so a shared base config is satisfied when its owner or the package extending it lists the package; an ignore-dependencies entry of the extending package silences it too. This holds for a config the package extends through its own node_modules ("extends": "./node_modules/<rig>/profiles/app/tsconfig-base.json", and what that profile extends): TypeScript merges the chain into the package’s options, so the tslib that an installed profile’s importHelpers needs is a use of the extending package’s manifest. The installed config is not judged, so nothing is reported there when the package does not list it. A types entry is satisfied by the package it names or its @types package: types: ["cypress"] with cypress listed at the root needs nothing more, and @cloudflare/workers-types or @types/node name themselves. types: ["*"] names no package: it keeps every @types package visible, so a globals-only one such as @types/chrome counts as used. A config without types keeps them all too before TypeScript 6, and none from TypeScript 6, which defaults types to []: there an @types package is used only when an import, a types entry or a /// <reference types> names it. An import of a package uses its @types package only when the installed package declares no types of its own (a non-empty types or typings in its package.json naming a file the package holds), as TypeScript reads those first: with eslint 9 installed, import type { Linter } from 'eslint' leaves @types/eslint unused. A package that is not installed keeps its @types package used, and so does a subpath import (kit/helpers), which the package’s own types may not cover. A config’s own types and typeRoots replace the ones it extends, and a later extends entry overrides an earlier one. A solution config whose references name other configs (files: [] beside tsconfig.app.json) keeps every package when one of the configs does. The version is that of the typescript installed in the nearest node_modules from the package up to the workspace root, else the lowest version the package’s typescript ranges admit (^6, >=6 <8 and 6.1.0-beta are 6; <6 and ^5 || ^6 are below), a catalog: reference read from the workspace catalogs and a peerDependencies range only when the package lists typescript nowhere else, else that of the root manifest; when none names one, every @types package stays visible.

ignore-dependencies silences a package; a config below node_modules, that git ignores (generated, such as .nuxt/tsconfig.json), in a fixture directory (unless include-fixtures) or matched by ignore is not judged. Production mode judges no config, and so strict, which implies it, judges none either. With isolate-workspaces outside production mode, a config is judged against the manifest of its own package only.

declare module 'pkg' declares the package, so its imports need no dependency, and so does a pattern with a literal start (declare module 'pkg/*') for the imports it matches. A declared subpath (declare module 'pkg/data.json') declares that module only: the package’s other imports still need it listed. Such a declaration in a script (a file without top-level import or export) stands in for the package and uses no listed pkg; in a module file the block augments the package, which uses it. An import that an alias leads into another package (react to preact/compat) is covered by a declaration of any module of that package. A specifier that names a workspace package is an import of that package also when a tsconfig mapping or a bundler alias resolves it into the package’s directory, to generated code there included; an alias into other code (ui/* to ./src/ui/* beside a workspace package ui) stays local. Such a local import uses no listed dependency either: with ui in dependencies and every import of ui/... mapped into ./src/ui, unused-dependencies reports ui, as the compiler never reaches the package. knip counts the dependency as used. An aliased import that reaches no file (a missing target, generated code not there yet, a computed alias) still uses the listed package its name starts with.

A directory below a package with a package.json of its own that is not an analysed workspace member (one excluded with ignore-packages included) is a separate project, often a root of its own in a recursive run (a build or scripts folder with its own lockfile); a package.json holding only type, sideEffects or imports is a marker for the files below it and makes no project, and so is one that adds only main, module, types, typings or browser in a directory the package above publishes as a subpath (its exports has ./<dir> or its files lists the directory, also as server/* or server/**), as pkg/server/package.json does for pkg/server in packages written before exports. The files that manifest points at are then entries of the package above. The files of a separate project are not the analysed root’s: when a script or an import of the root reaches one, that file is not reported in the root, and its imports are neither unlisted there nor uses of the root’s dependencies. The nested project judges the file against its own manifest when it is analysed as a root of its own. In the other direction, a file of the analysed root that a script of a package.json above it runs (up to the git repository root) is an entry, so node build/npm/postinstall.ts in the outer project keeps build/npm/postinstall.ts used in the nested root at build (except in production mode, where only the start script of the package’s own manifest gives entries).

In a multi-root run (skif -r) the files of a nested root that an enclosing root of the same run imports, runs from a script or names in a tool configuration are entries of the nested root: import { x } from "../build/lib/x" in the outer src keeps build/lib/x.ts, and what it imports, used in the root at build, and so does a workflow step node build/lib/report.ts for build/lib/report.ts. Only the files the enclosing root’s own code and configuration reach directly become entries, so an unused export of a file they import is still reported. A file an enclosing root’s plugin names as a build source (a Bazel srcs of the outer BUILD file) is a build source of the nested root instead: used, and what it imports too, but its unused exports are reported. A file the enclosing root both imports (or names as an entry) and builds from is an entry of the nested root, so its exports are public. A nested root is therefore linted after the roots that enclose it. A root linted on its own (skif build) cannot know what an outer root it was not given imports or builds from, so there such a file is still reported unused; lint from the top with -r, or add it to entry.

A file a root’s code reaches outside the root’s own directory counts as used by the root of the run that holds it: require("../tools/detect.js") in a nested root at build keeps the outer root’s tools/detect.js, and every file it imports in turn, out of unused-files, and so does an import of a file of a sibling root. The packages those files import count as used by the manifest that lists them at or above the file, so a sibling’s lib.js that requires lodash keeps lodash out of that sibling’s unused-dependencies. Those files are credited after every root is linted, so their exports are not judged against that code; linted on its own, the owning root still reports them.

The other way round, a nested root that imports or runs a dependency it does not list itself, but a package.json above it does, uses that dependency through the outer project’s node_modules: Node.js resolves it from there. In a multi-root run the root that owns that manifest (the innermost one that lists the dependency) then does not report it in unused-dependencies or unused-dev-dependencies, so gulp-rename in the root devDependencies stays used when only build/lib/gulp.ts of a nested root at build imports it. The outer root linted on its own cannot see the nested root’s code and still reports it.

A package with no source file at or below its directory, no entry and no script, such as a remote/package.json that only lists what code elsewhere in the repository installs it for, has no code skif could check its dependencies against, so they are not judged, as for a package whose entry files skif cannot determine. A pnpm install hook (.pnpmfile.cjs, .pnpmfile.mjs) is no source file for this rule: it is an entry, so what it imports is used, but a package whose only JavaScript it is stays unjudged.

A bare import of a builtin name (import { EventEmitter } from "events") uses a listed npm package of that name, the polyfill a bundler resolves it to for the browser; knip reports such a package unused. node:events names only the builtin, and events/ only the package.

The default project globs include .vue, .svelte and .astro files. Their <script> blocks (<script setup>, <script context="module">, any lang="ts" or lang="tsx") and the Astro frontmatter are analysed as modules, with diagnostics located in the original file. The markup is scanned, not compiled: component tags (<MyCard>, <my-card>, <ui.Card>), the expressions of {{ }}, { }, :prop, v-*, @event, Svelte blocks ({#if x}) and directives (use:action) count as uses of the imports they name, and a read such as ns.member counts as a use of that member. <style> blocks and src attributes of <script> and <style> tags are imports. The expressions are parsed as JavaScript, so a name an expression binds itself (items.map((item) => item.id)) is no use, and neither is a template local: the alias of a Vue v-for and the props of v-slot, #name and slot-scope, and the names Svelte’s {#each}, {#await}, {:then}, {:catch}, {#snippet}, {@const} and let: bind, within the element or block that binds them. A member that such a local of the same name as a namespace import reads (item.title under v-for="item in items") is no use of that namespace’s export; a named import keeps its export used either way, as in knip. An expression that does not parse is read token by token, which can only make an import look more used. Nothing in a template is type-checked. Imports of one script block count as used when another block reads them. In a .svelte file only the module script (<script context="module"> in Svelte 4, <script module> in Svelte 5) declares exports: export let and the other exports of the instance <script> are props and instance accessors, which unused-exports does not judge. A reached .svelte file uses the svelte package its package lists. The Props interface or type alias an Astro frontmatter exports types the component’s props, so it is used whenever the component, its default export, is.

.mdx files are read without an MDX compiler: their top-level import and export statements (at the first column, outside frontmatter and fenced code, as MDX delimits them) are analysed as JavaScript with JSX, and the prose is scanned for the components and expressions it uses, as in a component template. Imports written in code samples, inline code and frontmatter are not imports, and a component in a code sample or inline code (`<Card/>`) is not a use. A reached .mdx file uses the @mdx-js/* and remark-mdx packages its package lists. .mdx files are not in the default project globs: they are followed when an entry glob (Docusaurus docs, Astro pages, Storybook stories) or an import reaches them, and reported as unused only when project names them.

The templateUrl, styleUrl and styleUrls of an Angular or Stencil @Component({ … }) (the decorator imported from @angular/core or @stencil/core) are imports of the component file, relative to it with or without ./, so the stylesheets are followed and the packages they import count as used. This includes Stencil’s styles per mode (styleUrls: { ios: 'a.ios.css', md: ['a.md.css'] }); its assetsDirs are directories copied as they are, not modules, and are not followed. Vue auto-imports are followed through the declaration files unplugin-vue-components and unplugin-auto-import generate (components.d.ts, auto-imports.d.ts). A component components.d.ts registers from a file of the project is used where a template uses its tag, as knip compiles it: each .vue file whose template names AppButton the way Vue resolves a tag (AppButton, app-button, appButton, or LazyAppButton and lazy-app-button), in a static is attribute (<component is="AppButton">, :is="'AppButton'"), and each file that calls resolveComponent('AppButton'), imports the default export of the file AppButton is registered from. A registered component nothing uses so is reported by unused-files, and so is what only it imports. Native elements (<button>) never name a component, and the imports added for components are no circular-imports cycle. Registrations apply to every workspace of the run. A component registered from a package stays an import of the declaration file. A package that may use its components in files skif records no tags for keeps every component it registers used: one with a .tsx or .jsx project file, a VitePress or VuePress site, or a bundler config that passes the plugin an include matching more than .vue files (/\.md$/) or options skif cannot read. auto-imports.d.ts is an entry, as every declaration file that declares globals is, so each composable it registers counts as used, whether or not a file names it. A generated file that .gitignore excludes is not read, and the components it registers then look unused.

Stylesheets that code imports are followed: @import, @use, @forward and the Tailwind at-rules of .css, .scss, .sass, .less and .pcss files, and @import and @require of Stylus (.styl, .stylus, and <style lang="stylus"> blocks), where a bare name is looked up next to the file before it is taken as a package and a glob (@import "mixins/*") is skipped. A url() elsewhere in a stylesheet is an asset and is not followed, except one that names a file of a package, ~pkg/file or @scope/pkg/file with npm-valid names (url("@ibm/plex/fonts/a.woff2"), read without a query or fragment such as ?#iefix): it uses the package. An unscoped bare url(images/bg.png) is relative to the stylesheet and @/… is an alias, so neither names a package. Such a url() of a package that no manifest lists and that is not installed goes through a bundler alias skif cannot see (url('@assets/images/bg.png'), Nuxt’s url(~assets/logo.svg), a webpack resolve.modules directory) or names a missing asset, so unlisted-dependencies does not report it. A reached Stylus file uses the stylus package. .tsrx files (@tsrx/core) are not TypeScript a parser accepts, so only their import statements and import() calls are read: the packages and files they name are used, every imported binding counts as used as a whole, and their exports are not known, so a re-export (export { x } from './y') is not followed and ./y is not reached through it. A reached .tsrx file uses the @tsrx/* packages its package lists. Like .mdx, .tsrx files are not in the default project. .marko files are read the same way, and so are the imports of their <style> blocks and concise style { … } blocks (style.less { … } is Less, style { … } Sass); a tag import (import Card from "<card>") names no module and is left out. A reached .marko file uses the marko package, and .marko files are not in the default project either.

Test files are entries when a test-runner plugin is enabled (Jest, Vitest, Mocha, Playwright, Cypress and the like), with the patterns of that plugin; a project without a runner reports unused test files like any other, as knip does. Jest’s defaults include files named just test.js or spec.ts. Jest’s testRegex (a string, a regular expression or an array of them) selects test files too, besides the default test globs, which stay as knip keeps them; testMatch adds to them as well. A testRegex is matched against / and the path relative to the package, <rootDir> standing for the rootDir option (the config’s directory by default) and anchoring the expression there when it leads; the i, m and s flags of a regular expression literal apply. An expression the analysis cannot compile (a lookaround or a backreference) leaves the package’s files unjudged. testPathIgnorePatterns is not applied, as knip does not apply it either. A test file resolves its imports as every other file does, in TypeScript’s order: when sum.ts and sum.js sit side by side, ../sum and ../sum.js name sum.ts, while Jest (whose default moduleFileExtensions lists js before ts) loads sum.js and knip resolves both to it. Jest’s moduleFileExtensions is not read. A .js file beside a .ts file of the same name is most often the build output of that file, which this order keeps from standing in for its source; a hand-written twin that only such imports reach is reported by unused-files, so list it in entry or ignore. A Playwright testMatch regular expression becomes a glob when it is made of literals, .*, character classes ([jt]), the ? quantifier, anchors and groups (/.*\.e2e\.tsx?/ matches **/*.e2e.ts{x,}* below testDir); any other expression makes every script below testDir an entry. A Playwright webServer command is read as a script: the file it runs is an entry and the binaries it runs are judged. When the config computes it (a condition it cannot decide, a template literal with a port from the environment), every command of the config file is read instead, each branch of a condition counting and a substitution whose value is not known read as a shell variable (`bun e2e/serve.ts --port ${port}` runs e2e/serve.ts). Add other test files to entry. Directories named fixtures or __fixtures__ hold test data: their imports are not checked for unresolved or unlisted packages, and their files are not reported by unused-files nor their exports by unused-exports, unused-types, the namespace rules, unused-enum-members and unused-class-members. include-fixtures = true reports those files and exports like any other. A fixture file is still read when an entry reaches it, but one that nothing reaches is not, so a dependency only an unreached fixture imports stays unused. Other directories of test data (api-fixtures, __testfixtures__) and other test file names (*_spec.*) go on ignore and entry. In a package whose exports contain a wildcard ("./*": "./src/*.ts") the * matches across directories, as in Node.js, so every file it matches is an entry; the catch-all "./*" and the main, bin and types fields are not widened. In an enum or a namespace, a member read in its own file (E.A, E["A"], const { A } = E) counts as used. Using the whole enum there (Object.values(E), E[key], a spread, passing it as a value, typeof E, keyof typeof E or `${E}` in a type) uses every member of it, where knip credits none; a type annotation x: E names the enum type and uses no member (ADR 0009). A namespace used as a whole in its own file credits none of its members. Inside a namespace, a member read by its bare name (findVisible(), token: ProgressToken) counts as used, unless a parameter or local of the same name shadows it; the declarations of a merged namespace share their members. A file that another loads with new URL("./x", import.meta.url) is used as a whole, its types included: it runs as a program of its own, as an entry does. A bare file name with a code extension (new URL("worker.mjs", import.meta.url)) names the file beside the importer, as URL resolution reads it; a bare path with a directory is left out, since bundlers may read it as a package. So is a worker thread started from a path built from the file’s directory (new Worker(path.join(__dirname, "../workers/job.js")), also path.resolve, with string literals after __dirname); a plain string path is resolved against the working directory at run time and is not followed. A module that a test mocks (vi.mock("x"), jest.mock("x"), jest.requireActual("x") and the like, read from the syntax tree, so a call written inside a string does not count) stays reachable, and a listed package it names is used, but mocking a package that no package.json lists is not an unlisted import; a { virtual: true } mock is ignored. A relative or aliased mock whose module does not exist (vi.mock("./gone"), Vitest’s vi.mock(import("./gone")); a query such as ?react is dropped before resolving) is reported by stale-mocks, an error as such a call was under unresolved-imports, so that it can be triaged or baselined apart; a package name that resolves to nothing is not reported. In an n8n node package the files listed in package.json n8n.nodes and n8n.credentials are entries; a dist/nodes/A.node.js there maps to nodes/A.node.ts, since such packages compile without a rootDir. The vite and vitest plugins honour Vite’s root (relative to the config file): root: "src" makes the scripts of src/index.html entries, and a /-rooted script src or build input HTML file starts at src; a root that is not a static string leaves the package’s entries incomplete. A /-rooted script is also the file of that path in Vite’s publicDir (public below the root by default; publicDir: false turns it off), and leading path segments that are placeholders a server fills in with its base path (/{{BASE_PATH}}/static/init.js, /%BASE%/init.js) are skipped. The build input is read from build.rolldownOptions.input (Vite 8), else from build.rollupOptions.input, as knip reads it.

The table holds 213 built-in plugins:

typescript, eslint, prettier, vite, vitest, jest, next, storybook, playwright, tailwind, postcss, babel, webpack, rspack, rollup, tsup, turbo, husky, lint-staged, commitlint, changesets, github-actions, mastra, aws-cdk, browser-extension, tsdown, oxlint, angular, karma, esbuild, svelte, nuxt, astro, drizzle, ts-node, tsx, nx, cypress, mocha, sveltekit, prisma, graphql-codegen, docusaurus, vitepress, wrangler, expo, react-native, metro, release-it, semantic-release, lefthook, simple-git-hooks, stylelint, markdownlint, cspell, nodemon, pm2, pnpm, yarn, syncpack, node, expo-router, tanstack-router, ava, biome, c8, dotenv, electron-vite, gatsby, i18next-parser, jasmine, knex, lingui, msw, nest, netlify, nitro, nyc, oclif, panda-css, plop, preconstruct, react-router, remark, remix, rolldown, rsbuild, rslib, sanity, sentry, size-limit, stryker, svgo, svgr, swc, tsd, typedoc, unbuild, unocss, vercel, vike, tap, oxfmt, bun, unplugin-icons, webdriver-io, pre-commit, parcel, next-intl, dependency-cruiser, commitizen, electron-forge, serverless-framework, github-action, vue, unplugin-auto-import, unplugin-vue-components, unplugin-vue-router, mdx, next-mdx, starlight, pino, execa, zx, nano-spawn, azure-pipelines, sapper, tauri, capacitor, convex, payload, wxt, hardhat, temporal, react-email, openapi-ts, danger, changelogen, purgecss, fumadocs, nuxtjs-i18n, playwright-ct, sst, qwik, quasar, stencil, eleventy, cucumber, relay, orval, vite-plugin-pwa, xo, textlint, rstest, sveltejs-package, taskfile, mise, moonrepo, wireit, travis, buf, nano-staged, astro-db, astro-og-canvas, bumpp, changelogithub, create-typescript-app, eve, expressive-code, kysely-codegen, lockfile-lint, lost-pixel, node-modules-inspector, vercel-og, vite-pwa-assets-generator, astro-markdoc, borp, ladle, linthtml, lunaria, marko, mcp, mdxlint, npm-package-json-lint, osls, playwright-test, raycast, react-cosmos, tsrs, varlock, yorkie, filesystem-routing, flue, laravel-vite-plugin, railway, solidjs-vite-plugin, vite-plugin-pages, vite-plugin-vue-layouts-next, vite-plus, openclaw, typescript-content-mapper, lit, catalyst, fast, taskr, bazel, knip, evalite, mikro-orm, web-test-runner, unplugin-vue-i18n, unplugin-vue-markdown and heft.

A JavaScript or TypeScript config is evaluated statically. A value it imports from another file of the project, or from a workspace package (through its exports or main, mapped back to the source file), is evaluated in that module too: a base config merged with mergeConfig, spread into an object, or listed in an ESLint defineConfig. A value imported from an installed package stays unknown, and an imported value that depends on itself through imports is unknown there. An imported value the config changes (base.build.outDir = "out", withPlugins(base), a write through a local holding it, at the top level or in a function) is read as changed, as a local is; a method called on a namespace import (shared.make()) is taken to change nothing of it. A change through one import of a module reaches its other imports (ns.default and the default import, two exports that may be one object), and imported values of other modules too, as one may hold another, and so may what a function imported from such a module returns (getBase()), unless the function builds and returns new objects: a change of what such a factory returns (config.test.setupFiles.push("./setup.ts") after const config = createVitestConfig(options)) leaves only that part partly unknown, and reaches a value of the factory’s module only at a place of the result that may hold one. Calling a function of a project module or a workspace package that changes a value of a module (an import of its own, a binding it exports, also through a function of another module it calls, through what the function keeps for every call, such as f.cache = base, add.bind(null, base) or what a generator or async function made when the module is loaded was given, and through this or super where that may be such a value, a binding taking what this holds included), or that the module re-exports or hands out from such a module or from one that is neither followed nor installed (export { tweak } from "./tweak", export * from "./tools", import { tweak } from "./tweak"; export { tweak }, export const tools = { tweak }), calling a function of a bare import that is neither followed nor installed (a tsconfig alias such as @app/setup), and importing or requiring a module for its effects only (import "./setup"), leaves every value imported from such modules partly unknown; a module whose functions change no such value (a factory that builds and returns a new config) leaves them known, as does a re-export of a file that holds no code (a declaration file, JSON, a stylesheet, an asset). this is no value of a module in a constructor or a field initialiser giving the new instance a key (this.options = options), in a method of a class no code the module runs when it is loaded constructs, and in a method of an object a call makes, such as the hooks of a Vite or Rollup plugin a factory returns (load(id) { this.addWatchFile(id); }); it may be one in a method of an object the module makes when it is loaded, in a static method, in a function the module hands out or binds (add.bind(base)), and in any method of a module that calls one on another object (call, apply, bind given an object, a read of a prototype). What a module imported for its values does when it is loaded is not followed. A define… call (defineConfig({ … })) is the value it is given, and a merge (mergeConfig, merge, Object.assign) the merge of what it is given, only when its name is a global or comes from an installed package the evaluator does not follow; one from a module, a workspace package or a tsconfig alias of the project (@app/tools) it cannot follow, or a function the config takes from an object it declares (const { defineProperty } = Object), is unknown. A bare specifier counts as an installed package when it names no workspace package and a node_modules directory at or above the config holds it, or, in a project whose node_modules directories from the config up to the workspace root hold no package (none at all, or only the caches of tools such as .vite and .cache), whenever it names no workspace package. Under Yarn Plug’n’Play (a .pnp.cjs or .pnp.loader.mjs at the workspace root), a dependency the package holding the config or the root declares from a registry is installed, and no other name is. A member of a known object is the value of its key: { ...base, plugins: [...base.plugins, "x"] } keeps the plugins of the imported base, which are judged against the package that owns the module naming them, while "x" belongs to the importing config. An optional member (base?.plugins, undefined when base is null or undefined) and a computed member whose key is a known string or number (base["plugins"], base[KEY], LIST[0]) read the same way. Only a fully known object answers for a key it does not have, which is undefined there, read through a member or a destructuring; a key an unknown spread may set, a member of Object.prototype such as toString, and any key of an object with a __proto__ are unknown. A key merged from a spread with an unknown test ({ ...(ci ? { setupFiles: ["./a.ts"] } : {}) }) may be absent, so x.setupFiles ?? ["./default.ts"] keeps both lists and its .length is unknown. The same holds for every value that carries the read on: a constant or local holding it, an object key it is put in, set on or merged into, a function argument, a function’s return value, an array spreading it, and a named export holding it in an imported module. A parameter or destructuring default applies to a key an object does not have, but not to a literal null. A config function the tool calls (an exported function, the callback given to defineConfig) has every parameter unknown, its default included, since the tool passes what the config does not say: (env = {}) => env.analyze ? a : b keeps both branches. A config factory of a workspace package (createVitestConfig({ setupFiles: ["./setup.ts"] }), also wrapped as defineConfig(createBase(options))) is called with the arguments given, so what it builds from its options is known. A config that exports the result of a call that cannot be followed, such as a factory of an installed package, is unknown and leaves the package’s entries incomplete, but each string of the call’s arguments that names an existing file of the package as a path (./setup.ts, test/setup.ts), relative to the config file, is an entry, as are those of such a call that the exported config function returns (() => createConfig({ ... })), that an exported mergeConfig is given, or that sits below the top level of the exported config ({ test: createTest({ setupFiles: ["./setup.ts"] }) }). A bare name such as chart.js is a package even where a file of that name exists, and a file listed under an exclusion key (exclude, excludeFiles, watchExclude, coverage.exclude, ignores, ignorePatterns, testPathIgnorePatterns, testIgnore) is left out. A conditional (cond ? a : b, &&, ||, ??) whose test is known takes its branch, so a key spread in only when pinCjs.length is truthy is left out when pinCjs defaults to []. A value with an unknown test is what both branches share: a key only one branch sets is unknown and the other keys stay known. A spread with an unknown test (...(tmp && { cacheDir: tmp }), ...(process.env.CI ? { test: { setupFiles: [...] } } : {})) adds every key a branch sets instead: a list gets the elements of every branch, so the files each branch names are entries, and any other value the branches do not share is unknown. Only a branch that is not known itself, such as an imported base config, makes it an unknown spread. The same holds for if (test) return a; before a function’s last return: a known test takes its branch, and with an unknown test the value is what both returns share, never the last one alone. .map, .flatMap and .filter of a known array call their callback, an inline function or one the config declares, with each element and its index, so ["light", "dark"].map((theme) => ({ test: { name: `browser-${theme}` } })) is two known projects; an element that is not known (a spread of an unknown list) stays unknown, and a predicate whose result is not known keeps the element. Object.fromEntries of a known list of [key, value] pairs is their object, template literals and + write known strings, numbers and booleans, and === and !== compare known primitives. A Vite or Vitest root that is one of several directories reads the HTML entries of each. A path function, a template literal or + over a value that is one of several is one of the results of each, unknown when one is unknown or there would be more than eight, so path.join(dir, 'vitest.setup.ts') with such a dir is one of two paths. The sep and delimiter of path are POSIX’s / and : (those of path.win32 are unknown). A list of files or patterns (setup files, test globs, bundler entries) whose value or element is one of several known strings makes each an entry candidate; one that names no file is dropped without a hint, unless it lies in build output, where it stands for its source or leaves the package incomplete as described under incomplete entries. A local assigned or changed in code that may or may not run (a branch with an unknown test, a loop, cond && (x = 1)), and a top-level constant changed after its declaration (if (process.env.A) config.plugins.push(…)), is unknown or partly unknown afterwards rather than keeping its earlier value; a branch with an unknown test that changes a local leaves it what both branches have in common. Only the part a change reaches is affected: config.module.rules.push(…) leaves module.rules partly unknown, config.output.path = … leaves output.path unknown, and the rest of config stays known; push and unshift of a local list add their elements. A change below a key a known object neither has nor inherits (config.plugins.push(…) without plugins) changes nothing, as reaching below undefined throws; below a key an unknown spread may set or the object may inherit (__proto__, constructor), the object is partly unknown. An object changed through another name for it (const a = cfg, { test: t }, { ...base }, a function given cfg), by a function that writes what it captures, by delete or inside an expression is partly unknown wherever it is read, in the part the change reaches; a write through an object that is not a name or a member chain (config.module.rules.find(…).loader = …, (prod ? config.prod : config.dev).devtool = false) reaches each part of a local that object may be. A call of a function the config declares shares with what it is given only what the function may return of it: a fresh object it builds shares nothing with its arguments, unless the function is used other than by calling it by name, calls itself or reads arguments; a getter, method or callback in what it returns shares what that returns, and a parameter shares its default (b = a). What a method returns (config.plugins.find(…), list.slice()) may be a part of the object it is called on. A const of a function that takes a local of that function, or a static part of it (const { coverage } = config.test), is followed instead when it is the only such name for the local, no other function shares either and the local is never assigned again: a change through it is applied to that part of the local, so coverage.enabled = true in a branch with an unknown test leaves enabled one of both values and the rest of config known. What else may hold that object (a list or object holding config, the options spread into it, another key of config given the same object) is partly unknown where it is read after the alias is declared. A resolve call (require.resolve, createRequire(...).resolve) changes nothing, and neither do the functions of path, url, JSON and Math, fs.readFileSync and the other reading functions of fs, Object.keys and console, so a config holding fs.readFileSync(CERT) stays known; a const holding a string or a number shares no object with what it is given to. JSON.stringify and JSON.parse count only when what follows their first argument is a literal that holds no function or undefined (JSON.stringify(config, null, 2)) and no argument is given through a spread: a replacer or reviver function is called with what they are given. These are known only where the name resolves to the module or global that declares it, never a local of the same name. Any other call, a library’s function or a new of a class other than a builtin one, may change every object it is given, in any position and through a spread, and every local an object or array literal it is given holds, at any depth (kit.fill({ cfg: config }), foo([config]), all of options for foo({ ...options })), unless it is a define… helper of a package the evaluator does not follow (one of a module of the project, ./tools, #tools or @/tools, or of a workspace package may change what it is given), a merge that copies (merge of webpack-merge, deepmerge given no options or options without a function, defu, the mergeConfig of Vite and Vitest), createRequire, or Object.assign, Object.defineProperties or Object.defineProperty and Reflect.defineProperty, which change only their first argument, the last two only the key they name when it is a string, unless that argument is given through a spread (Object.assign(...[config, extra])); these are no define… helpers. A define… helper and a merge that copies keep none of their arguments in another, so a change of one argument leaves the others known, and call no function they are given with anything of the config: the parameters of the callback of defineConfig((env) => ({ … })) take what the tool passes, so a change a plugin factory in it makes of what it is given does not reach the other keys the callback returns. A list or string method (push, slice, concat) changes at most its object only when that object is known to be a list or string, and one that calls a function it is given with the list’s elements (forEach, map, reduce) only when that function is written in place or declared by the config and no this object follows it (list.forEach(fn, thisArg)); an imported callback (configs.forEach(withSentry)) may change each element and that object. A local holding a function the evaluator does not follow (const addAlias = aliaser(config)) may change what it was made from each time it is called; one bound to an import or a require is taken to change none of the config’s locals. A method of a package the config only calls methods on (_.merge(…)) is taken to keep nothing it is given in the package; once the config stores a value in it, reads a member of it otherwise, gives it to a call or gives a method a function, a call’s result or an object holding one (store.set(() => config)), and for a workspace package the evaluator follows, what its methods return may hold what it holds. Object.assign onto an object literal (Object.assign({}, base)) copies the keys of what it is given, as a spread does. A change through an element of a list leaves every element open; a loop name, a callback parameter, a name a destructuring assignment sets and a function assigned with = share with what they take, except the element a callback or a loop over a const list or object of strings or numbers takes when no change reaches it, also through Object.entries, Object.values and Object.keys (a later parameter, such as the list forEach passes, still shares it), so Object.entries(pages).map(([name, template]) => new HtmlWebpackPlugin({ chunks: [name], template })) leaves entry: pages known; a value spread from an object literal (...(ci ? { plugins: list } : {})) is shared at the key it is spread at only; a write through one key reaches another key of the same local that holds the same object (config.b = config.a); a spread of a local ({ ...options }) copies its keys, so a change below one of them (options.coverage.enabled = true) reaches the copy at that key only, and a new value of a key of either leaves the other as it was; a write in a class body leaves what it reaches unknown; and the object of a with statement is partly unknown after it. A getter, a setter or an iterator of an object or class instance a module makes, also one Object.defineProperty, Object.defineProperties, Reflect.defineProperty or Object.create defines, that writes through this (get grow() { this.list.push(x) }) changes what the object holds where code runs it with no call written: a read or a write of its key; a destructuring in a declaration, an assignment, a parameter or a parameter of a callback ([config].map(({ grow }) => grow)); a spread; for…of, yield* and an array destructuring, which also run the next, return and throw of an iterator; a value of a tagged template; a call whose code skif does not visit; a builtin that reads the keys of what it is given (JSON.stringify, Object.assign); and a new of a class that is no builtin. A binding of this in it (const self = this, const { list } = this) is this, a getter run on this by another one counts for both, a getter that only gives a key of this a new value (this.mode = 'production') leaves that key unknown and the rest known, and a method it calls on this counts only as far as that method writes. A define… helper of a package, path.join and a list method given the object run none of them. Other code a value runs implicitly is not followed and may change what it reaches unseen: a static getter of a class, the toString or valueOf a template literal or String(x) calls, the toJSON of JSON.stringify, the then of an awaited object, and a getter, a setter or an iterator of an object another module makes; so is a change an imported function makes later to an object an earlier call gave it (register(config), then apply()). A key a plugin reads files from that is unknown below the top level, such as vitest’s setupFiles: isPostgres ? [...] : [] or a test object an unknown spread may replace, leaves the plugin’s entries incomplete instead of being read as empty.

Plugins read configs and sources statically and never run a tool, so some of knip’s plugin behaviour has no counterpart. These differences are deliberate:

  • react-router reads routes.ts as text: the string literals that name a source file are route modules, and a flatRoutes() call makes the files of its routes directory (rootDirectory, routes by default) route modules. ignoredRouteFiles is not applied and routes a program computes are not known. @react-router/node and isbot count as used but not as production dependencies.
  • knex finds knex({ client: "pg" }) calls by scanning source text, so only a string literal client in an object literal argument counts.
  • gatsby reads setBabelPlugin({ name }) calls of gatsby-node files as text, whatever hook they sit in.
  • rsbuild evaluates a config function once without parameters and does not call functions in tools.rspack.
  • rslib and preconstruct entries are production entries; knip also marks their exports as used, skif follows include-entry-exports.
  • size-limit credits every @size-limit/* package of the workspace, of any dependency kind; knip counts only dependencies and devDependencies. size-limit.{json,js,...} files are entries next to knip’s size-limit.config.* and .size-limit*.
  • biome resolves the "//" root reference to the biome.json of the farthest ancestor directory that has one.
  • For tsd, jasmine, ava, msw and oclif the default entry patterns apply also when the config names others.
  • Command lines are read from package.json scripts: jasmine and tsd positional arguments, stryker run <file>, typedoc --plugin and --theme. A flag that skif does not know takes the next word as its value, as minimist does, and c8 and dotenv follow the command they wrap.
  • execa, zx, nano-spawn and pino read the source files of the package as text before parsing those that mention the library. execa, zx and nano-spawn read only the files the module graph reaches, as knip does: a file nothing imports or runs, such as a test fixture, runs no command. A file that such a command runs (execa("node", ["scripts/next.mjs"])) is an entry, whose own commands count in turn. They also leave out the files of a workspace member below the package, whose commands are that member’s. A directory with a package.json that is no member (scripts/package.json that only sets "type": "module", an example project outside the workspace globs) is the package’s own. A command counts when it is literal: execa("tsx", ["build.ts"]), $`vite build` (the substitutions of a template are placeholders) or spawn("eslint", ["."]); a computed argument ends the command (spawn("node", [script, "out.js"]) runs no out.js), and a literal argument that is not a plain word ("a && b", an SQL statement) is one quoted word of the command. execa also reads the default export of execa 5 and earlier (execa.sync, execa.command, execa.node). zx reads $ in files that start with #!/usr/bin/env zx and, unlike knip, also where $ is imported from zx, in files that import zx/globals and under a shebang such as #!/usr/bin/env -S npx zx. In a file that switches zx to PowerShell (usePwsh(), usePowerShell() or $.shell = 'pwsh'), a cmdlet named Verb-Noun (New-Item) or a default PowerShell alias (gci, ni) is no binary.
  • bun is enabled by bun.lock, bun.lockb or bunfig.toml in the package, a bun test script, or @types/bun or bun-types in the package or a package above it. Its test entries are the files bun test finds: *.test.*, *_test.*, *.spec.* and *_spec.* with any of the js, jsx, ts, tsx, mjs, cjs, mts and cts extensions; with [test] root in bunfig.toml only those below that directory (relative to the config), and without the files and directories a glob of pathIgnorePatterns (relative to the config too) matches. Entries set for the plugin in [js.plugins] replace these as before. bunfig.toml names the modules of preload and [test] preload, the package of jsxImportSource, the security scanner of [install.security] scanner and the ESLint plugins of [lint] plugins. In the source files, the commands of Bun Shell ($`…` imported from bun, or Bun.$`…`) and of Bun.spawn and Bun.spawnSync (a list of words, a computed one left out, or { cmd }) are read like those of execa, and the entrypoints of Bun.build (or build imported from bun) are production entries relative to the package, the directory a script runs Bun in; one computed from the file’s own location (path.join(import.meta.dir, "worker.ts")) is relative to the file. A command run in another directory, by $`…`.cwd(dir) or the cwd option of Bun.spawn, is judged as one run in another package, as bun --cwd is. Only the package’s own sources are read: a workspace root does not read the files below a member’s package.json. A package whose sources, or the sources of the packages below it, use the Bun global uses the @types/bun or bun-types it lists.
  • next-mdx and starlight read the options of the @next/mdx and @astrojs/starlight calls in the config source; a plugin or component passed as an imported binding is not a string and is already an import.
  • unplugin-auto-import and unplugin-vue-components make the declaration files they generate (auto-imports.d.ts, components.d.ts) entries. A local component components.d.ts registers is used only where a template uses its tag, as in knip, unless the package may use it in files skif records no tags for (see above); every composable auto-imports.d.ts registers is used, while knip credits one only in the .vue and .ts files that name it.
  • unplugin-vue-markdown and unplugin-vue-i18n are enabled by their packages and add nothing else. knip compiles the Markdown files unplugin-vue-markdown turns into components, for the components their tags use; skif reads no Markdown, so where the unplugin-vue-components options of a bundler config include Markdown files, every component components.d.ts registers is used, and the imports of a Markdown page’s <script> blocks are not followed.
  • mikro-orm reads each options object of mikro-orm.config.*: one, a list, or what a config function returns, and the configs package.json#mikro-orm.configPaths names. The paths of entities and entitiesTs (a directory stands for every module below it), the migrations directory (migrations.pathTs, else path, else ./migrations, none with migrationsList) and the seeders directory are production entries, relative to baseDir or the workspace directory. knip calls a config function with the context name default; skif evaluates it with its parameters unknown, so a path computed from the context name is not known, and an entity given as a class is already an import of the config. The !(*.d) of the default migrations and seeders globs reads as *.
  • web-test-runner reads the files of its config and of the config’s groups, relative to the workspace directory, and the test files a script passes to wtr or web-test-runner: positional, with --files or after --.
  • vue reads configureWebpack as a webpack config. A function one is called statically with knip’s base config (mode, empty entry, resolve, plugins and module.rules): the object it returns, or the base config as it leaves it (config.entry = { … }), is read; what it reads from its argument’s members is not known, and an entry it sets to an unknown value marks the entries incomplete. It credits @vue/cli-plugin-eslint when a script runs vue-cli-service lint.
  • serverless-framework reads ${file(./x.yml)} and ${file(./x.yml):a.b} variables. In a handler, a ${self:a.b} variable is the string at a.b of the config, else its quoted fallback (${self:custom.dir, 'src'}), and any other variable (${opt:stage}, ${env:DIR}, also ${opt:stage, 'dev'}, whose fallback is only one of the values it takes), whose value is known only when the CLI runs, is a wildcard: ** when it fills a path segment, as it may stand for several, and * within one. A wildcard is a trade-off: it can still miss files (a variable within a segment that stands for a path) and makes a wider entry, which can keep an unused file from being reported. A handler that is a glob is an entry glob, unless it names any file (${opt:file}.main).
  • github-action leaves out the dist/ and build/ files an action.yml runs, as build output; knip also removes them from the project files.
  • azure-pipelines (the script and bash steps of azure-pipelines.yml, .azure-pipelines/** and the templates they include) and sapper (its fixed client, server, service worker and routes) have no knip counterpart. glob is no plugin: the command of glob -c "<command>" <patterns> is read where the script parser meets it.
  • sst, quasar, stencil and orval read their options wherever the config writes them (a handler inside run(), Stencil’s export const config), as knip does. sst also reads the handlers of the modules sst.config.ts imports by relative path (await import("./infra/api"), ./infra/api.js for infra/api.ts), so the SST 2 stacks of app.stack(…) too, and cuts the export off a .route() handler. It also reads the handler shorthand of SST 2 constructs: the string values of routes, subscribers, notifications and targets, and a function, job or consumer string. quasar takes the first sourceFiles, boot and css written anywhere.
  • qwik and stencil need no compiler for .mdx or Sass files: skif reads every reached .mdx file and Sass stylesheet itself, so Qwik City’s .mdx routes and the Sass of stencil’s component style URLs, which are imports of the component (see above), are read.
  • eleventy reads addPassthroughCopy("img") and addPassthroughCopy({ "src/js": "js" }) calls: a directory makes its JavaScript and TypeScript files production entries, a file or glob is one, and a path into node_modules names a package. A path computed from a local of the config function is not known.
  • rstest applies exclude (a list or { patterns }) and negated include patterns as ! entries below the project’s root, so its default test and mock globs do not bring an excluded file back. A ! entry removes files from all the package’s entries, so a file one project excludes is no entry of another project with the same root either; knip lists each project’s files instead. Rstest’s default exclusions (node_modules, dist, tool directories) are not added. rs.mock("x"), rs.doMock(), rs.importActual() and the other module calls of rs and rstest are mock imports, like vi.mock().
  • react-email credits @react-email/ui for a preview command from React Email 6 and @react-email/preview-server before, by the installed version (node_modules/react-email/package.json in the package or an ancestor up to the workspace root), else by the first number of the declared range; both when neither is known. payload keeps migrations and payload-types.ts from being reported through ignore.
  • mise reads file tasks under the directories of task_config.includes or, when no config sets includes, under mise-tasks/, .mise-tasks/, mise/tasks/, .mise/tasks/ and .config/mise/tasks/. A JavaScript or TypeScript file is an entry, and the command of its shebang (#!/usr/bin/env -S npx tsx) a script. An extensionless one run by node, bun, deno, tsx or ts-node makes the relative modules it imports entries, and those it only resolves (require.resolve) used files whose exports are judged. A shell script (a shebang of sh, bash, zsh, dash or ksh, or without a shebang one of those extensions) is a script run in its #MISE dir="…" (also # [MISE], //MISE) or the package. A task for another interpreter, or a file without a shebang whose extension is not a shell’s (README), is not read. knip reads no file tasks.
  • taskfile expands {{.NAME}} from the task’s and the Taskfile’s vars (a string only), {{.ROOT_DIR}} and {{.TASKFILE_DIR}}; any other template ({{.CLI_ARGS}}, an sh: variable, a function) is a word that is not known, so the rest of the command is still read, and an include holding one is skipped.
  • marko reads .marko files for their imports and style blocks (see above) but does not read the tag libraries of installed packages, so a package used only through its tags is not credited; it credits marko when a template exists.
  • varlock reads the @plugin and @import decorators in the root comments of the .env files under package.json#varlock.loadPath and those a script passes with --path, but not ~/ paths, and does not skip git-ignored files; a @plugin version (@varlock/1password-plugin@1.2.0) is cut off. railway counts a service whose source is a call (image("postgres")) as local, and knows the local repository from package.json#repository only, not from the git remotes. A service rootDirectory is read from the repository root (/apps/api is apps/api); one with .. drops the service’s commands.
  • openclaw and typescript-content-mapper are enabled by their package.json key. The files of OpenClaw assetScripts are entries, not production entries. mdxlint keeps a scoped plugin name as written.
  • solidjs-vite-plugin, filesystem-routing, vite-plugin-pages, vite-plugin-vue-layouts-next and flue keep their conventional production entries when they read a config, as every plugin does; knip replaces them.
  • An exported class registered as a custom element is used: customElements.define("x-y", Class) always counts (also through window.customElements, a variable holding the registry, or this in a static block), and so does the registering decorator of an enabled plugin’s library on a top-level class: lit’s @customElement, stencil’s @Component, catalyst’s @controller and fast’s @customElement, or a FASTElement subclass that calls Class.define() or is passed to FASTElement.define(Class, …). A decorator counts only when it is imported from that library. A variable holding the registry is resolved by scope; a local binding named customElements that does not hold the registry is not detected.
  • taskr has no knip counterpart: taskfile.js and the local plugins of package.json#taskr.requires are entries, and @taskr/* and taskr-* dependencies count as used, as taskr loads them by name.
  • knip has no knip counterpart: in a project that runs knip next to skif, with knip as a dependency, knip’s config files (knip.json, knip.jsonc, .knip.json, .knip.jsonc, knip.*, knip.config.* and the knip key of package.json) are configs, and the JavaScript and TypeScript ones are entries, so what they import is used.
  • heft has no knip counterpart. It is enabled by @rushstack/heft or a config/rig.json, and reads config/heft.json, config/typescript.json, config/jest.config.json and config/rig.json as JSON with comments. The package an extends path lies in (@rushstack/heft-node-rig/profiles/default/config/heft.json) and the pluginPackage of every lifecycle plugin (heftPlugins) and task plugin (phasesByName.<phase>.tasksByName.<task>.taskPlugin) are dependencies of the config; a relative extends is a further config. @rushstack/heft-sass-plugin credits sass, which it loads, without making it unlisted. A config/rig.json needs its rigPackageName, and the configs of the installed rig’s profile (node_modules/<rigPackageName>/profiles/<rigProfile>, default without rigProfile) are the project’s: each config/*.json the project’s own config folder lacks, and each tsconfig*.json, read by typescript. A rig that is not installed gives only the credit of the rig. In a rig package, profiles/*/config/*.json are its own configs, so the packages they extend and load are its dependencies, and a profile heft.json credits @rushstack/heft, which the rig provides to its projects. Its profiles/*/tsconfig*.json are configs it ships for the projects that extend them: the packages their compiler options name (types, importHelpers and the rest) are used when the rig lists them and never unlisted at the rig, and their paths, baseUrl and output directories are left out.
  • bazel has no knip counterpart. It is enabled by a BUILD.bazel or BUILD file at the top of a package and reads the BUILD files below the package as Starlark text, never evaluated, in a Bazel repository whose MODULE.bazel, REPO.bazel, WORKSPACE.bazel or WORKSPACE names aspect_rules_js (the nearest one at or above the package, within the git repository). A label of the node_modules that npm_link_all_packages links for the package (":node_modules/esbuild", "//packages/app:node_modules/@types/node") and a load of a package’s package_json.bzl ("@npm//packages/app:esbuild/package_json.bzl") use that dependency; a label of another package’s node_modules belongs to that package, so "//:node_modules/typescript" in a member’s BUILD file uses the root’s typescript. The entry_point of js_binary, js_run_devserver and js_test is an entry, and the data of those rules and the srcs and data of js_library and ts_project are build sources: used files whose imports are followed but whose exports, types and members are judged, as they are no entries. A literal counts when it names an existing file of the package, by path or as ":path" (one of a workspace member below the package is an entry or build source of that member, and one of a nested root an entry or build source of that root under skif -r), and those of js_test only outside --production; glob(), select() and variables name nothing, nor does a macro of a .bzl file. The BUILD files of a nested package give no entries or build sources, and those below the bazel-* links at the repository root are not read.
  • A tsconfig with outDir maps build output back to source through its rootDir. Without one, skif takes the longest common directory of the include patterns (each up to its first wildcard) and the files, not counting declaration files; TypeScript computes it from the files it compiles. A config with neither keeps the dist to src convention. A file a script runs inside an outDir (node build/src/cli.js) is its source file, even when the build output is on disk, and a directory mocha is given (mocha build/compiled/test) stands for the code files directly in its source directory, or every one below it with --recursive. Only files with an --extension value (js, cjs and mjs by default) count, and in a source directory behind an outDir also the TypeScript sources that compile to them. An include entry without a wildcard is a file only when it ends in a code or .json extension (packages/v1.2 is a directory).

A root takes every configuration file from its own directory up to the root of the git repository (the nearest directory with a .git entry, a directory or a worktree file), farthest first, and merges them. Outside a repository the search covers the root alone in a single-workspace run and the start directory in a recursive run. A file above the repository is never read. A file with root = true ends the search at itself. skif inside a project and skif -r from the top therefore give that project the same configuration. The guide Sharing configuration shows complete examples.

root = true
extends = ["../presets/node-cli.toml"]
reset = ["version-groups"]
  • root = true stops the upward search at this file. It is only valid in a file found by discovery.
  • extends lists files, relative to the declaring file or absolute. They apply before the declaring file, in order. A file reached twice applies once. A cycle, a missing file or more than 16 nested files is an error naming the file.
  • reset discards what was inherited for the listed keys before this file applies. Allowed values: version-groups, semver-groups, update-groups, custom-types, ignore, dependency-families, overrides.
Value Rule
Scalars (fail-on-warnings, package-manager, mode, …) The later file replaces
Tables ([workspace], [lint], [policy], [catalog], [js], …) Merge key by key
Arrays of strings The later file replaces
extend-ignore-packages ([workspace]), extend-ignore, extend-ignore-dependencies, extend-ignore-binaries, extend-ignore-unresolved ([js] and [js.workspaces."<dir>"]), extend-exclude ([catalog]) Append to the inherited list, after the plain key of the same file
[rules] Per rule: a level keeps the inherited options; a table of options replaces the options and keeps the level
[js.plugins] Per plugin: true or false keeps the options; a table replaces them
[js.compilers] Per extension: an entry replaces the inherited one
[[ignore]], [[overrides]] Append
[[version-groups]], [[semver-groups]], [[update-groups]] The nearer file’s entries come first, so with first match wins the project beats the org
[[dependency-families]], [[custom-types]] Replace the entry of the same name, append the others
[[overrides]]
packages = ["./legacy/**", "@acme/old-*"] # directories start with ./, other entries are names
files = ["**/src/generated/**"] # file globs, anchored at the declaring file
max-level = "warn" # cap the severity of matched diagnostics
[overrides.rules]
unused-exports = "off"
[[overrides.ignore]]
rules = ["unlisted-dependencies"]
dependencies = ["jquery"]
[overrides.js] # needs packages, no files
entry = ["src/server.ts"]
extend-ignore-dependencies = ["@acme/test-utils"]

At least one of packages and files is required; when both are set a diagnostic must match both. An override changes how diagnostics in the selected packages or files are reported, and which JS inputs those packages get. It never changes what a workspace-wide analysis computes, so a package leaves version policy through a root-level version group with policy = "ignored".

Package-scoped keys, the only ones an override or a package file may hold: rules (levels only), max-level, ignore, and in js: entry, project, ignore, ignore-dependencies, ignore-binaries, ignore-unresolved, the matching extend- keys and plugins. Any other key, including rule options, js.enabled and js.production, is an error that names the key, the file and the line. [lint] max-level caps a whole root and is allowed in a base file. A plain js key replaces the inherited list, and = [] clears it (ignore-dependencies = [] lets a package report what the workspace table ignores). A dependency-types entry may name a [[custom-types]] entry of an inherited file; the names are resolved on the merged configuration. A rule that is off in the base and on in an override runs; its diagnostics outside the override are dropped.

A skif.toml in the directory of a workspace member applies to that package only, as if it were an override with packages = ["./"]. It uses the top-level spelling ([rules], [js], [[ignore]], [lint] max-level) and the same package-scoped keys. Its [[ignore]] entries need no filter. root, extends and [[overrides]] are not allowed in it.

Patterns that select packages or files in an override, and extends paths, are relative to the directory of the file that declares them. $ROOT/ at the start of a pattern anchors it at the root being linted instead, which a shared preset needs. A pattern that would leave its anchor (../packages/* in config/shared.toml) never matches, and a lint run warns about it on stderr, naming the file: write $ROOT/packages/* instead. A lint run also warns about a pattern that selects nothing at any root that reads it: a path pattern of a file that lies neither in the root nor above it, such as a --config file in another directory, whose files and ./ patterns are anchored at that directory (write them with $ROOT/), and a packages pattern of a file in the root that matches no package. Patterns of a file above the root are not judged, since that file may configure other roots, and nor are files patterns inside the root. Values are read in the scope they configure: top-level [js] globs are relative to the root, js globs of an override or package file are relative to each package. ignore-packages, [[ignore]] packages, group selectors and [js.workspaces] keys stay relative to the root, with one exception: in a multi-root run with --config <FILE>, the [js.workspaces] keys and ignore-workspaces globs of that file are relative to the directory the run starts at. "." is then the root in that directory only, "tools/sub" the root in tools/sub, and "tools/sub/packages/*" the members of that root, so one file can configure every root of the run by its directory. The keys then depend on where the run starts: from the repository root the root in tools/sub is "tools/sub", from tools/ it is "sub", so write the file for the directory your recursive runs start at.

skif config --show prints the effective configuration of each root as TOML with a # from <file>:<line> comment on every value some file set (the last file to set it, plus the files that appended to a list), and lists the skif.toml files below the root that were not applied, with the reason: only the root’s own directory and the directories of its workspace members are read. --format json adds the same as data: origins (every key with the assignments that built it) and not-applied (path and reason). skif config --explain <key> [--package <name>] prints every file that touched a key and the final value. --config <FILE> lints with that file (and what it extends) only, and --no-config reads no file.

Every key that names packages or dependencies is a list of names and globs. ! negates, and an invalid pattern is a configuration error naming the key.

#:schema https://raw.githubusercontent.com/polylint/skif/main/schema/skif.schema.json
[workspace]
ignore-packages = ["examples/*"]
[lint]
fail-on-warnings = true
[rules]
unsorted-dependencies = "warn"
empty-dependencies = "off"
[[ignore]]
rules = ["types-in-dependencies"]
packages = ["legacy-app"]
[catalog]
mode = "prefer"
[js]
enabled = true