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.
Precedence
Section titled “Precedence”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.
Editor support
Section titled “Editor support”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.
Sections
Section titled “Sections”| 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]
Section titled “[workspace]”[workspace]ignore-packages = ["examples/*", "!examples/keep"]package-manager = "pnpm" # npm | pnpm | yarn | bun; overrides detectiondiscover-ignore = ["fixtures", "e2e/cases"] # directories `skif -r` does not search for rootsdiscover-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]
Section titled “[lint]”[lint]fail-on-warnings = true # exit non-zero when only warnings were reportedmax-level = "warn" # cap the severity of every finding of the rootrequire-ignore-reasons = true # fail when a suppression has no `reason`, as --require-ignore-reasons doesrequire-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.
[rules]
Section titled “[rules]”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 | errorempty-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 files
Section titled “Toolchain files”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 teamFROM node:18-alpine# skif-ignore-next-line foreign-package-manager-command -- fallback for the 1.x release branchRUN 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.
[[ignore]]
Section titled “[[ignore]]”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]
Section titled “[policy]”[policy]prefer = "highest" # highest | lowestdependency-types = ["peer"] # empty means prod, dev and local; name peer or optional to include themoverride-reading = "skif" # skif | syncpack; how resolutions, overrides and pnpm-overrides entries are readdependency-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.
[[version-groups]]
Section titled “[[version-groups]]”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]]
Section titled “[[semver-groups]]”[[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.
[[custom-types]]
Section titled “[[custom-types]]”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.jsonstrategy = "version" # version | name@version | versions-by-name | name~version
[[custom-types]]name = "package-manager"path = "packageManager" # "pnpm@9.15.0": the dependency is pnpmstrategy = "name@version"
[[custom-types]]name = "runtime"path = "volta.toolVersion" # the versionname-path = "volta.tool" # the dependency name, read from another fieldstrategy = "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]
Section titled “[catalog]”[catalog]mode = "prefer" # off | prefer | enforcemin-packages = 2 # packages using a dependency before an entry is suggestedexclude = ["typescript"]report-unused-entries = true # default false: `unused-catalog-entries` reports nothing unless this is setA [[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]
Section titled “[workspace-protocol]”[workspace-protocol]internal = true # require workspace: for dependencies on workspace packagesallow-local-paths = false # accept file:/link: paths for internal dependenciesThe 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]]
Section titled “[[dependency-families]]”[[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 familypackages = ["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 reactIn 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.
[update]
Section titled “[update]”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 offmax-concurrent-requests = 12 # registry requests at once, at least 1Without 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]]
Section titled “[[update-groups]]”[[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 aloneThe 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.
[format]
Section titled “[format]”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 ordersort-packages = true # the remaining top-level keys in byte order; false keeps their ordersort-az = ["bin", "contributors", "dependencies", "devDependencies", "keywords", "peerDependencies", "resolutions", "scripts"]sort-exports = ["types", "default"] # types first, default last, every other condition where it isformat-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 layoutsort-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 = trueentry = ["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 = trueignore-unresolved = ["#internal/*", "/^virtual:/"]ignore-workspaces = ["tools/*"]ignore-members = ["/^_/"]ignore-exports-used-in-file = { type = true, interface = true }production = falseisolate-workspaces = falsestrict = falseinclude-entry-exports = falsetsconfig = "tsconfig.app.json"use-tsconfig-files = falseinclude-fixtures = falseuse-public-hoisting = falsediscovery = "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 = truepaths = { "@/*" = ["./src/*"] }
[js.workspaces."packages/web".plugins]vite = { config = ["vite.web.config.ts"] }
[js.plugins]vitest = truejest = { 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.tsfrom the file’s directory,litas a package), so a missing file is reported byunresolved-importsand a package the manifest does not list byunlisted-dependencies. The imports bring in no names, likeimport "./x". The patterns are compiled by the Rustregexengine (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 knowtw = { 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: anentrypattern 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. Withinclude-entry-exports, only plugin entry globs and the manifest count, since a configured entry has its exports judged.project-redundant: aprojectpattern that is a plain path to an entry file, which is always in the project. Not judged withuse-tsconfig-files.entry-top-levelandproject-top-level: the top-levelentryorprojectin 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: aprojectpattern 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 knipprojectglob such assrc/**/*.{ts,css}keeps working unchanged. Neither are the extensions of[js.compilers].project-extension-excluded:projectpatterns that name extensions but not.vue,.svelteor.astrowhile 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 inmain,module,browser,bin,types,typingsorexportsthat names no file, neither itself nor a source file behind it. Paths a.gitignorehides, 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 inpackage.json. A path in abindirectory 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 indist/...still is not. Abinpath is not judged when a build step of the package may write it: abuild,build:*,prepackorprepublishOnlyscript, 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 atsconfigoutDirat or insidebin. 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.tsforbin/stack.js), also when a.gitignorehides it (*.js): the compiler names each output after a source file, so abin/stack.jsno 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-unconfiguredandworkspace-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
publicHoistPatternandshamefullyHoistfrompnpm-workspace.yaml, elsepublic-hoist-patternandshamefully-hoistfrom the top level of the root.npmrc, which pnpm 11 no longer reads for these settings (so.npmrcis skipped when the root’spackageManagernames pnpm 11 or later). The patterns hoist into the rootnode_modules, so they apply to every package.*matches any run of characters, a!pattern excludes what the patterns before it include, andshamefully-hoist = trueis 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_packagesof rules_js’snpm_translate_lock, in the Bazel repository root’sMODULE.bazel,WORKSPACE.bazelorWORKSPACE, when it is a dict literal: each key (a version suffix such as@1.2.3dropped) is available to the packages at or below each Bazel package its list names,""being the repository root.
[js]use-public-hoisting = truewith 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-routerreadsroutes.tsas text: the string literals that name a source file are route modules, and aflatRoutes()call makes the files of its routes directory (rootDirectory,routesby default) route modules.ignoredRouteFilesis not applied and routes a program computes are not known.@react-router/nodeandisbotcount as used but not as production dependencies.knexfindsknex({ client: "pg" })calls by scanning source text, so only a string literalclientin an object literal argument counts.gatsbyreadssetBabelPlugin({ name })calls ofgatsby-nodefiles as text, whatever hook they sit in.rsbuildevaluates a config function once without parameters and does not call functions intools.rspack.rslibandpreconstructentries are production entries; knip also marks their exports as used, skif followsinclude-entry-exports.size-limitcredits every@size-limit/*package of the workspace, of any dependency kind; knip counts onlydependenciesanddevDependencies.size-limit.{json,js,...}files are entries next to knip’ssize-limit.config.*and.size-limit*.biomeresolves the"//"root reference to thebiome.jsonof the farthest ancestor directory that has one.- For
tsd,jasmine,ava,mswandoclifthe default entry patterns apply also when the config names others. - Command lines are read from
package.jsonscripts:jasmineandtsdpositional arguments,stryker run <file>,typedoc --pluginand--theme. A flag that skif does not know takes the next word as its value, asminimistdoes, andc8anddotenvfollow the command they wrap. execa,zx,nano-spawnandpinoread the source files of the package as text before parsing those that mention the library.execa,zxandnano-spawnread 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 apackage.jsonthat is no member (scripts/package.jsonthat 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) orspawn("eslint", ["."]); a computed argument ends the command (spawn("node", [script, "out.js"])runs noout.js), and a literal argument that is not a plain word ("a && b", an SQL statement) is one quoted word of the command.execaalso reads the default export of execa 5 and earlier (execa.sync,execa.command,execa.node).zxreads$in files that start with#!/usr/bin/env zxand, unlike knip, also where$is imported fromzx, in files that importzx/globalsand 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 namedVerb-Noun(New-Item) or a default PowerShell alias (gci,ni) is no binary.bunis enabled bybun.lock,bun.lockborbunfig.tomlin the package, abun testscript, or@types/bunorbun-typesin the package or a package above it. Its test entries are the filesbun testfinds:*.test.*,*_test.*,*.spec.*and*_spec.*with any of thejs,jsx,ts,tsx,mjs,cjs,mtsandctsextensions; with[test] rootinbunfig.tomlonly those below that directory (relative to the config), and without the files and directories a glob ofpathIgnorePatterns(relative to the config too) matches. Entries set for the plugin in[js.plugins]replace these as before.bunfig.tomlnames the modules ofpreloadand[test] preload, the package ofjsxImportSource, the security scanner of[install.security] scannerand the ESLint plugins of[lint] plugins. In the source files, the commands of Bun Shell ($`…`imported frombun, orBun.$`…`) and ofBun.spawnandBun.spawnSync(a list of words, a computed one left out, or{ cmd }) are read like those ofexeca, and theentrypointsofBun.build(orbuildimported frombun) 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 thecwdoption ofBun.spawn, is judged as one run in another package, asbun --cwdis. Only the package’s own sources are read: a workspace root does not read the files below a member’spackage.json. A package whose sources, or the sources of the packages below it, use theBunglobal uses the@types/bunorbun-typesit lists.next-mdxandstarlightread the options of the@next/mdxand@astrojs/starlightcalls in the config source; a plugin or component passed as an imported binding is not a string and is already an import.unplugin-auto-importandunplugin-vue-componentsmake the declaration files they generate (auto-imports.d.ts,components.d.ts) entries. A local componentcomponents.d.tsregisters 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 composableauto-imports.d.tsregisters is used, while knip credits one only in the.vueand.tsfiles that name it.unplugin-vue-markdownandunplugin-vue-i18nare enabled by their packages and add nothing else. knip compiles the Markdown filesunplugin-vue-markdownturns into components, for the components their tags use; skif reads no Markdown, so where theunplugin-vue-componentsoptions of a bundler configincludeMarkdown files, every componentcomponents.d.tsregisters is used, and the imports of a Markdown page’s<script>blocks are not followed.mikro-ormreads each options object ofmikro-orm.config.*: one, a list, or what a config function returns, and the configspackage.json#mikro-orm.configPathsnames. The paths ofentitiesandentitiesTs(a directory stands for every module below it), the migrations directory (migrations.pathTs, elsepath, else./migrations, none withmigrationsList) and the seeders directory are production entries, relative tobaseDiror the workspace directory. knip calls a config function with the context namedefault; 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-runnerreads thefilesof its config and of the config’sgroups, relative to the workspace directory, and the test files a script passes towtrorweb-test-runner: positional, with--filesor after--.vuereadsconfigureWebpackas a webpack config. A function one is called statically with knip’s base config (mode, emptyentry,resolve,pluginsandmodule.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 anentryit sets to an unknown value marks the entries incomplete. It credits@vue/cli-plugin-eslintwhen a script runsvue-cli-service lint.serverless-frameworkreads${file(./x.yml)}and${file(./x.yml):a.b}variables. In ahandler, a${self:a.b}variable is the string ata.bof 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-actionleaves out thedist/andbuild/files anaction.ymlruns, as build output; knip also removes them from the project files.azure-pipelines(thescriptandbashsteps ofazure-pipelines.yml,.azure-pipelines/**and the templates they include) andsapper(its fixed client, server, service worker and routes) have no knip counterpart.globis no plugin: the command ofglob -c "<command>" <patterns>is read where the script parser meets it.sst,quasar,stencilandorvalread their options wherever the config writes them (ahandlerinsiderun(), Stencil’sexport const config), as knip does.sstalso reads the handlers of the modulessst.config.tsimports by relative path (await import("./infra/api"),./infra/api.jsforinfra/api.ts), so the SST 2 stacks ofapp.stack(…)too, and cuts the export off a.route()handler. It also reads the handler shorthand of SST 2 constructs: the string values ofroutes,subscribers,notificationsandtargets, and afunction,joborconsumerstring.quasartakes the firstsourceFiles,bootandcsswritten anywhere.qwikandstencilneed no compiler for.mdxor Sass files: skif reads every reached.mdxfile and Sass stylesheet itself, so Qwik City’s.mdxroutes and the Sass ofstencil’s component style URLs, which are imports of the component (see above), are read.eleventyreadsaddPassthroughCopy("img")andaddPassthroughCopy({ "src/js": "js" })calls: a directory makes its JavaScript and TypeScript files production entries, a file or glob is one, and a path intonode_modulesnames a package. A path computed from a local of the config function is not known.rstestappliesexclude(a list or{ patterns }) and negatedincludepatterns 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 ofrsandrstestare mock imports, likevi.mock().react-emailcredits@react-email/uifor a preview command from React Email 6 and@react-email/preview-serverbefore, by the installed version (node_modules/react-email/package.jsonin the package or an ancestor up to the workspace root), else by the first number of the declared range; both when neither is known.payloadkeeps migrations andpayload-types.tsfrom being reported throughignore.misereads file tasks under the directories oftask_config.includesor, when no config setsincludes, undermise-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 bynode,bun,deno,tsxorts-nodemakes the relative modules it imports entries, and those it only resolves (require.resolve) used files whose exports are judged. A shell script (a shebang ofsh,bash,zsh,dashorksh, 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.taskfileexpands{{.NAME}}from the task’s and the Taskfile’svars(a string only),{{.ROOT_DIR}}and{{.TASKFILE_DIR}}; any other template ({{.CLI_ARGS}}, ansh: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.markoreads.markofiles 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 creditsmarkowhen a template exists.varlockreads the@pluginand@importdecorators in the root comments of the.envfiles underpackage.json#varlock.loadPathand those a script passes with--path, but not~/paths, and does not skip git-ignored files; a@pluginversion (@varlock/1password-plugin@1.2.0) is cut off.railwaycounts a service whosesourceis a call (image("postgres")) as local, and knows the local repository frompackage.json#repositoryonly, not from the git remotes. A servicerootDirectoryis read from the repository root (/apps/apiisapps/api); one with..drops the service’s commands.openclawandtypescript-content-mapperare enabled by theirpackage.jsonkey. The files of OpenClawassetScriptsare entries, not production entries.mdxlintkeeps a scoped plugin name as written.solidjs-vite-plugin,filesystem-routing,vite-plugin-pages,vite-plugin-vue-layouts-nextandfluekeep 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 throughwindow.customElements, a variable holding the registry, orthisin 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@controllerandfast’s@customElement, or aFASTElementsubclass that callsClass.define()or is passed toFASTElement.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 namedcustomElementsthat does not hold the registry is not detected. taskrhas no knip counterpart:taskfile.jsand the local plugins ofpackage.json#taskr.requiresare entries, and@taskr/*andtaskr-*dependencies count as used, as taskr loads them by name.kniphas no knip counterpart: in a project that runs knip next to skif, withknipas a dependency, knip’s config files (knip.json,knip.jsonc,.knip.json,.knip.jsonc,knip.*,knip.config.*and theknipkey ofpackage.json) are configs, and the JavaScript and TypeScript ones are entries, so what they import is used.hefthas no knip counterpart. It is enabled by@rushstack/heftor aconfig/rig.json, and readsconfig/heft.json,config/typescript.json,config/jest.config.jsonandconfig/rig.jsonas JSON with comments. The package anextendspath lies in (@rushstack/heft-node-rig/profiles/default/config/heft.json) and thepluginPackageof every lifecycle plugin (heftPlugins) and task plugin (phasesByName.<phase>.tasksByName.<task>.taskPlugin) are dependencies of the config; a relativeextendsis a further config.@rushstack/heft-sass-plugincreditssass, which it loads, without making it unlisted. Aconfig/rig.jsonneeds itsrigPackageName, and the configs of the installed rig’s profile (node_modules/<rigPackageName>/profiles/<rigProfile>,defaultwithoutrigProfile) are the project’s: eachconfig/*.jsonthe project’s ownconfigfolder lacks, and eachtsconfig*.json, read bytypescript. A rig that is not installed gives only the credit of the rig. In a rig package,profiles/*/config/*.jsonare its own configs, so the packages they extend and load are its dependencies, and a profileheft.jsoncredits@rushstack/heft, which the rig provides to its projects. Itsprofiles/*/tsconfig*.jsonare configs it ships for the projects that extend them: the packages their compiler options name (types,importHelpersand the rest) are used when the rig lists them and never unlisted at the rig, and theirpaths,baseUrland output directories are left out.bazelhas no knip counterpart. It is enabled by aBUILD.bazelorBUILDfile at the top of a package and reads theBUILDfiles below the package as Starlark text, never evaluated, in a Bazel repository whoseMODULE.bazel,REPO.bazel,WORKSPACE.bazelorWORKSPACEnamesaspect_rules_js(the nearest one at or above the package, within the git repository). A label of thenode_modulesthatnpm_link_all_packageslinks for the package (":node_modules/esbuild","//packages/app:node_modules/@types/node") and a load of a package’spackage_json.bzl("@npm//packages/app:esbuild/package_json.bzl") use that dependency; a label of another package’snode_modulesbelongs to that package, so"//:node_modules/typescript"in a member’sBUILDfile uses the root’stypescript. Theentry_pointofjs_binary,js_run_devserverandjs_testis an entry, and thedataof those rules and thesrcsanddataofjs_libraryandts_projectare 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 underskif -r), and those ofjs_testonly outside--production;glob(),select()and variables name nothing, nor does a macro of a.bzlfile. TheBUILDfiles of a nested package give no entries or build sources, and those below thebazel-*links at the repository root are not read.- A
tsconfigwithoutDirmaps build output back to source through itsrootDir. Without one, skif takes the longest common directory of theincludepatterns (each up to its first wildcard) and thefiles, not counting declaration files; TypeScript computes it from the files it compiles. A config with neither keeps thedisttosrcconvention. A file a script runs inside anoutDir(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--extensionvalue (js,cjsandmjsby default) count, and in a source directory behind anoutDiralso the TypeScript sources that compile to them. Anincludeentry without a wildcard is a file only when it ends in a code or.jsonextension (packages/v1.2is a directory).
Layered configuration
Section titled “Layered configuration”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, extends and reset
Section titled “root, extends and reset”root = trueextends = ["../presets/node-cli.toml"]reset = ["version-groups"]root = truestops the upward search at this file. It is only valid in a file found by discovery.extendslists 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.resetdiscards 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.
Merge rules
Section titled “Merge rules”| 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]]
Section titled “[[overrides]]”[[overrides]]packages = ["./legacy/**", "@acme/old-*"] # directories start with ./, other entries are namesfiles = ["**/src/generated/**"] # file globs, anchored at the declaring filemax-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 filesentry = ["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.
Package files
Section titled “Package files”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.
Inspecting the result
Section titled “Inspecting the result”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.
Selectors
Section titled “Selectors”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.
Full example
Section titled “Full example”#: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