:::

Acknowledgements Copy Chapter

Thanks to Joshua Goldberg for emoji-blast! 🎉

Packages Docs Src Content Docs Explanations Comparison And Migration (`packages/docs/src/content/docs/explanations/comparison-and-migration.md`) Copy Section

title: Comparison & Migration Copy Chapter

First of all, Knip owes a lot to the projects on this page and they've all been
inspirational in their own way. For best results, Knip has a vision embracing
comprehensiveness which is larger in scope than any of the alternatives. So
if any of those tools has the right scope for your requirements, then by all
means, use what suits you best. Note that most projects are no longer
maintained.

All tools have in common that they have less features and don't support the
concept of monorepos/workspaces. Feel free to send in projects that Knip
does not handle better, Knip loves to be challenged!

Migration Copy Chapter

A migration consists of deleting the dependency and its configuration file and
getting started with Knip. You should end up with less configuration.

Comparison Copy Chapter

depcheck Copy Section

Depcheck is a tool for analyzing the dependencies in a project to see:
how each dependency is used, which dependencies are useless, and which
dependencies are missing from package.json.

The project has plugins (specials), yet not as many as Knip has and they're not
as advanced. It also supports compilers (parsers) for non-standard files.

The following commands are similar:

depcheck
knip --dependencies

Project status: The project is archived and recommends Knip.

unimported Copy Section

Find and fix dangling files and unused dependencies in your JavaScript
projects.

unimported is fast and works well. It works in what Knip calls "production
mode" exclusively. If you're fine with a little bit of configuration and don't
want or need to deal with non-production items (such as devDependencies and
test files), then this might work well for you.

The following commands are similar:

unimported
knip --production --dependencies --files

Project status: The project is archived and recommends Knip.

ts-prune Copy Section

Find unused exports in a typescript project. 🛀

ts-prune aims to find potentially unused exports in your TypeScript project
with zero configuration.

The following commands are similar:

ts-prune
knip --include exports,types,nsExports,nsTypes

Use knip --exports to also include enum and namespace members.

Project status: The project is archived and recommends Knip.

ts-unused-exports Copy Section

ts-unused-exports finds unused exported symbols in your Typescript
project

The following commands are similar:

ts-unused-exports
knip --include exports,types,nsExports,nsTypes

Use knip --exports to also include enum and namespace members.

tsr Copy Section

Remove unused code from your TypeScript Project

tsr (previously ts-remove-unused) removes unused exports, and works based
on a single tsconfig.json file (includes and excludes) and requires no
configuration. It removes the export keyword or the whole export declaration.

Project status: The project is archived and recommends Knip.

Related projects Copy Chapter

Additional alternative and related projects include:

• deadfile
• DepClean
• dependency-check
• find-unused-exports
• next-unused
• npm-check
• renoma

In general, the e18e.dev website and in particular the Cleanup
section is a great resource when dealing with technical debt.

Packages Docs Src Content Docs Explanations Entry Files (`packages/docs/src/content/docs/explanations/entry-files.md`) Copy Section

title: Entry Files Copy Chapter

Entry files are the starting point for Knip to determine what files are used in
the codebase. More entry files lead to increased coverage of the codebase. This
also leads to more dependencies to be discovered. This page explains how Knip
and its plugins try to find entry files so you don't need to configure them
yourself.

Default entry file patterns Copy Chapter

For brevity, the default configuration on the previous page mentions only
index.js and index.ts, but the default set of file names and extensions is
actually a bit larger:

• index, main and cli
• js, mjs, cjs, jsx, ts, mts, cts and tsx

This means files like main.cjs and src/cli.ts are automatically added as
entry files. Here's the default configuration in full:

{
  "entry": [
    "{index,cli,main}.{js,cjs,mjs,jsx,ts,cts,mts,tsx}",
    "src/{index,cli,main}.{js,cjs,mjs,jsx,ts,cts,mts,tsx}"
  ],
  "project": ["**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx}!"]
}

Next to the default locations, Knip looks for entry files in other places. In
a monorepo, this is done for each workspace separately.

The values you set override the default values, they are not merged.

Plugins Copy Chapter

Plugins often add entry files. For instance, the Remix, Storybook and Vitest
plugins add additional entry files. See the next page about plugins for
more details about this.

Scripts in package.json Copy Chapter

The package.json is scanned for entry files. The main, bin, and exports
fields may contain entry files. The scripts are also parsed to find entry
files and dependencies. See Script Parser for more details.

Ignored files Copy Chapter

Knip respects .gitignore files. By default, ignored files are not added as
entry files. This behavior can be disabled by using the --no-gitignore
flag on the CLI.

Configuring project files Copy Chapter

See configuring project files for guidance on tuning entry and project
and when to use ignore.

Where Knip looks for entry files Copy Chapter

Putting it together, Knip discovers entry files from:

• Default locations such as index.js and src/index.ts
• The main, bin and exports fields in package.json
• Entry and config files added by enabled plugins (the config files are entry
  files too)
• Dynamic imports: require() and import()
• require.resolve() and import.meta.resolve()
• new URL('./file.js', import.meta.url)
• new Worker(…) and child_process fork/spawn/execFile when the target
  is path.join(__dirname, …)
• module.register('./loader.js') loader registration
• Scripts the script parser extracts: package.json scripts, CI workflow
  run commands, and source-code calls (tagged $ templates,
  node:child_process, execa, nano-spawn)

Entry files are added to the module graph, and module resolution may pull in
further entry files recursively until none remain.

Packages Docs Src Content Docs Explanations How Knip Works (`packages/docs/src/content/docs/explanations/how-knip-works.md`) Copy Section

title: How Knip works Copy Chapter

Knip finds and removes unused code and dependencies. It starts at your entry
files, follows every import to the files they reach, and builds a graph of
everything connected. Anything left out is reported as unused: a file no entry
reaches, an export no file imports, a dependency no file uses.

This page explains how Knip produces its results.

Build and analyze Copy Chapter

Knip runs in two phases.

The build phase starts from the entry files. Knip reads a file, parses it,
collects its imports and exports, resolves each import to another file, and
repeats for every newly reached file. The result is a graph of the project:
every reachable file, what it imports, and what imports it.

Resolution is broad by design. Knip follows custom path aliases and extensions,
reads references out of config files and shell scripts, and "compiles"
non-standard files like .vue and .svelte so their imports are in the graph
too.

The analysis phase queries that graph. It never re-parses anything. It walks the
edges already recorded:

• a file is unused when no entry reaches it
• an export is unused when no other file imports it
• a dependency is unused when no file imports it (and unlisted when a file
  imports it but package.json doesn't list it)

Analysis happens by quering the graph. Your results are only as accurate as the
graph is complete. And the graph depends on your entry files.

Entry files decide what Knip can see Copy Chapter

The graph contains only what's reachable from an entry file. Miss one entry, and
everything reachable only from it looks unused.

Ideally you don't need to list entries by hand. Knip starts from sensible
defaults like src/index.ts, and plugins automatically add the entry
points specific to your frameworks and libraries. The Vitest plugin adds your
test files, the Astro plugin adds your pages, and so on. This is why plugins are
important: each one tells Knip about a whole class of files it might otherwise
never reach.

Findings come in chains Copy Chapter

Unused results cascade. They don't appear in isolation. Say a tool generates an
entry file Knip doesn't know about:

• that file looks unused, because nothing reaches it
• every file it imports looks unused too, because nothing else reaches them
• every export in those files looks unused
• every dependency only those files used looks unused

One unreached entry can turn into dozens of findings. The chain also runs in
reverse: add the entry, and the whole cascade collapses at once.

So read the output from the root down: unused files first, then exports, then
dependencies. A single unused file usually explains a long list of results
below it. Fix causes at the root and the rest disappears.

Some chains only show up one run at a time. An export counts as used when
another file imports it, even if the importing code is unused. Remove that code,
and the next run may report the export. Unused exports that import each other
across files are never reported.

A surprising result might be a gap, not a bug Copy Chapter

When Knip flags something you're sure is used, it's based on the graph: it
couldn't reach that code from an entry. The cause is usually one of:

• a missing entry for a tool or convention Knip doesn't know yet
• a dynamic import Knip can't follow statically, or a path it can't resolve
• a transitive dependency of a package that resolves only because something else
  installs it

In each case the fix is to teach Knip: add the entry, configure the plugin, list
the dependency. Don't hide the result. Configuring project files and
resolving reported issues cover how, issue type by issue type.

Packages Docs Src Content Docs Explanations Plugins (`packages/docs/src/content/docs/explanations/plugins.md`) Copy Section

title: Plugins Copy Chapter

This page describes why Knip uses plugins and the difference between config
and entry files.

Knip has an extensive and growing list of built-in plugins. Feel free to
write a plugin so others can benefit too!

What does a plugin do? Copy Chapter

Plugins are enabled if the related package is listed in the list of dependencies
in package.json. For instance, if astro is listed in dependencies or
devDependencies, then the Astro plugin is enabled. And this means that this
plugin will:

• Handle configuration files like astro.config.mjs
• Add entry files such as src/pages/**/*.astro
• Define command-line arguments

Configuration files Copy Chapter

Knip uses entry files as starting points to scan your source code and
resolve other internal files and external dependencies. The module graph can be
statically resolved through the require and import statements in those
source files. However, configuration files reference external dependencies in
various ways. Knip uses a plugin for each tool to parse configuration files and
find those dependencies.

Example: ESLint Copy Section

In the first example we look at the ESLint plugin. The default config
file patterns include .eslintrc.json. Here's a minimal example:

{
  "extends": ["airbnb", "prettier"],
  "plugins": ["@typescript-eslint"]
}

Configuration files like this don't import or require anything, but they do
require the referenced dependencies to be installed.

In this case, the plugin will return three dependencies:

• eslint-config-airbnb
• eslint-config-prettier
• @typescript-eslint/eslint-plugin

Knip will then look for missing dependencies in package.json and report those
as unlisted. And vice versa, if there are any ESLint plugins listed in
package.json, but unused, those will be reported as well.

Example: Vitest Copy Section

The second example uses the Vitest plugin. Here's a minimal example of a
Vitest configuration file:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'istanbul',
    },
    environment: 'happy-dom',
  },
});

The Vitest plugin reads this configuration and returns two dependencies:

• @vitest/coverage-istanbul
• vitest-environment-happy-dom

Knip will look for missing and unused dependencies in package.json and report
accordingly.

Some tools allow configuration to be stored in package.json, that's why some
plugins contain package.json in the list of config files.

:::tip[Summary]

Plugins load configuration files to find referenced dependencies, and determine
unused and unlisted dependencies.

:::

Entry files Copy Chapter

Many plugins have default entry files configured. When the plugin is enabled,
Knip will add entry files as configured by the plugin to resolve used files and
dependencies.

For example, if next is listed as a dependency in package.json, the Next.js
plugin will automatically add multiple patterns as entry files, such as
pages/**/*.{js,jsx,ts,tsx}. If vitest is listed, the Vitest plugin adds
**/*.{test,test-d,spec,spec-d}.ts as entry file patterns. Most plugins have
entry files configured, so you don't have to.

It's mostly plugins for meta frameworks and test runners that have entry files
configured.

:::tip[Plugins result in less configuration]

Plugins use entry file patterns as defined in your configuration file of these
tools. So you don't need to repeat this in your Knip configuration.

:::

For example, let's say your Playwright configuration contains the following:

import type { PlaywrightTestConfig } from '@playwright/test';

const config: PlaywrightTestConfig = {
  testDir: 'integration',
  testMatch: ['**/*-test.ts'],
};

export default config;

The Playwright plugin will read this configuration file and return those entry
patterns (integration/**/*-test.ts). Knip will then not use the default entry
patterns.

You can still override this behavior in your Knip configuration:

{
  "playwright": {
    "entry": "src/**/*.integration.ts"
  }
}

This should not be necessary though. Please consider opening a pull request or a
bug report if any plugin is not behaving as expected.

:::tip[Summary]

Plugins try hard to automatically add the correct entry files.

:::

Entry files from config files Copy Chapter

Entry files are part of plugin configuration (as described in the previous
section). Yet plugins can also return additional entry files after parsing
configuration files. Below are some examples of configuration files parsed by
plugins to return additional entry files. The goal of these examples is to give
you an idea about the various ways Knip and its plugins try to find entry files
so you don't need to configure them yourself.

Angular Copy Section

The Angular plugin parses the Angular configuration file. Here's a fragment:

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "projects": {
    "knip-angular-example": {
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:browser",
          "options": {
            "outputPath": "dist/knip-angular-example",
            "main": "src/main.ts",
            "tsConfig": "tsconfig.app.json"
          }
        }
      }
    }
  }
}

This will result in src/main.ts being added as an entry file (and
@angular-devkit/build-angular as a referenced dependency).

Additionally, the Angular plugin returns tsconfig.app.json as a configuration
file for the TypeScript plugin.

GitHub Actions Copy Section

This plugin parses workflow YAML files. This fragment contains three run
scripts:

jobs:
  integration:
    runs-on: ubuntu-latest
    steps:
      - run: npm install
      - run: node scripts/build.js
      - run: node --loader tsx scripts/deploy.ts
      - run: playwright test -c playwright.web.config.ts
        working-directory: e2e

From these scripts, the scripts/build.js and scripts/deploy.ts files will be
added as entry files by the GitHub Actions plugin.

Additionally, the file e2e/playwright.web.config.ts is detected and will be
handed over as a Playwright configuration file.

Read more about this in command-line arguments.

webpack Copy Section

Let's take a look at this example webpack configuration file:

module.exports = env => {
  return {
    entry: {
      main: './src/app.ts',
      vendor: './src/vendor.ts',
    },
    module: {
      rules: [
        {
          test: /\.(woff|ttf|ico|woff2|jpg|jpeg|png|webp)$/i,
          use: 'base64-inline-loader',
        },
      ],
    },
  };
};

The webpack plugin will parse this and add ./src/app.ts and ./src/vendor.ts
as entry files. It will also add base64-inline-loader as a referenced
dependency.

:::tip[Summary]

In your config files, plugins can find additional entry files and also other
config files recursively.

:::

Bringing it all together Copy Chapter

Sometimes a configuration file is a JavaScript or TypeScript file that imports
dependencies, but also contains configuration that needs to be parsed by a
plugin to find additional dependencies.

Let's take a look at this example Vite configuration file:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig(async ({ mode, command }) => {
  return {
    plugins: [react()],
    test: {
      setupFiles: ['./setup-tests.ts'],
      environment: 'happy-dom',
      coverage: {
        provider: 'c8',
      },
    },
  };
});

This file imports vite and @vitejs/plugin-react directly, but also
indirectly references the happy-dom and @vitest/coverage-c8 packages.

The Vite plugin of Knip will dynamically load this configuration file and
parse the exported configuration. But it's not aware of the vite and
@vitejs/plugin-react imports. This is why such config files are also
automatically added as entry files for Knip to statically resolve the
import and require statements.

Additionally, ./setup-tests.ts will be added as an entry file.

:::note

When plugins dynamically load configuration files, conditional dependencies may
not be detected if the condition evaluates differently during analysis. See
conditional or dynamic dependencies for details and workarounds.

:::

Command-Line Arguments Copy Chapter

Plugins may define the arguments where Knip should look for entry files,
configuration files and dependencies. We've already seen some examples above:

node --loader tsx scripts/deploy.ts
playwright test -c playwright.web.config.ts

Please see script parser for more details.

Config File Location Copy Chapter

If configuration files aren't in their default location and they are not
referenced through some script like vite -c ./dir/vite.config.ts, then make
sure to tell Knip about it. Two examples:

{
  "playwright": { "config": ["e2e/playwright.config.ts"] },
  "vite": "packages/*/vite.config.ts" // shorthand without `config` and array notation
}

This is common in projects where a directory like packages/lib is not an
actual workspace with a package.json file. Also see integrated monorepos
for similar cases.

Summary Copy Chapter

:::tip[Summary]

Plugins are configured with two distinct types of files:

• config files are dynamically loaded and parsed by the plugin
• entry files are added to the module graph
• Both can recursively lead to additional entry files, config files and
  dependencies

:::

Packages Docs Src Content Docs Explanations Why Use Knip (`packages/docs/src/content/docs/explanations/why-use-knip.md`) Copy Section

title: Why use Knip? Copy Chapter

The value of removing clutter is clear, but finding it manually is tedious. Meet
Knip: comprehensive and accurate results at any scale.

:::tip[TL;DR]

Unused files, exports and dependencies pile up as projects grow. Removing them
improves maintenance, performance, security and onboarding, and prevents
regressions in CI. Knip automates finding (and fixing) all three,
comprehensively and at any scale.

:::

Less is more Copy Chapter

There are plenty of reasons to delete unused files, dependencies and "dead
code":

• Easier maintenance: things are easier to manage when there's less of it.
• Improved performance: startup time, build time and/or bundle size can be
  negatively impacted when unused code, files and/or dependencies are included.
  Relying on tree-shaking when bundling code helps, but it's not a silver
  bullet.
• Increased security: less code and dependencies means less room for weak spots.
• Easier onboarding: there should be no doubts about whether files, dependencies
  and exports are actually in use or not. Especially for people new to the
  project and/or taking over responsibilities this is harder to grasp.
• Prevent regressions: tools like TypeScript, ESLint and Prettier do all sorts
  of checks and linting to report violations and prevent regressions. Knip does
  the same for dependencies, exports and files that are obsolete.
• Keeping dead code around has a negative value on readability, as it can be
  misleading and distracting. Even if it serves no purpose it will need to be
  maintained (source: Safe dead code removal → YAGNI).
• Also see Why are unused dependencies a problem? and Why are unused
  exports a problem?.

Automation Copy Chapter

Code and dependency management is usually not the most exciting task for most of
us. Knip's mission is to automate finding clutter. This is such a tedious job if
you were to do it manually, and where would you even start? Knip applies many
techniques and heuristics to report what you need and save a lot of time.

:::tip

Knip not only finds clutter, it can also remove clutter!

Use Knip next to a linter like ESLint or Biome: after removing unused variables
inside files, Knip might find even more unused code. Rinse and repeat!

:::

Comprehensive Copy Chapter

You can use alternative tools that do the same. However, the advantage of a
strategy that addresses all of dependencies, exports and files is in their
synergy:

• Utilizing plugins to find their dependencies includes the capacity to find
  additional entry and configuration files. This results in more resolved and
  used files. Better coverage gives better insights into unused files and
  exports.
• Analyzing more files reveals more unused exports and dependency usage,
  refining the list of both unused and unlisted dependencies.
• This approach is amplified in a monorepo setting. In fact, files and
  internal dependencies can recursively reference each other (across
  workspaces).

Knip reaches this coverage through fine-grained entry points, custom
module resolution, configuration-file parsers, an advanced
shell-script parser, and built-in and custom compilers, then fixes
most of it automatically.

Greenfield or Legacy Copy Chapter

Installing Knip in greenfield projects ensures the project stays neat and tidy
from the start. Add it to your CI workflow and prevent any regressions from
entering the codebase.

:::tip

Use Knip in a CI environment to prevent future regressions.

:::

In large and/or legacy projects, Knip may report false positives and require
some configuration. It aims to be a great assistant when cleaning up parts of
the project or doing large refactors. Even a list of results with a few false
positives is many times better and faster than if you were to do it manually.

Unobtrusive Copy Chapter

Knip does not introduce new syntax for you to learn. This may sound obvious, but
consider comments like the following:

// eslint-disable-next-line
// prettier-ignore
// @ts-expect-error

Knip doesn't have similar comments like // knip-ignore so you can get rid of
false positives for a variety of reasons:

1. A false positive may be a bug in Knip, and should be reported, not dismissed.
2. Instead of proprietary comments, use standardized annotations that also
   serve as documentation.
3. In the event you want to remove Knip, just uninstall knip without having to
   remove useless comments scattered throughout the codebase.

Tip: use @lintignore in JSDoc comments, so other linters can use the same.

Packages Docs Src Content Docs Features Auto Fix (`packages/docs/src/content/docs/features/auto-fix.mdx`) Copy Section

title: Auto-fix Copy Chapter

import { Tabs, TabItem } from '@astrojs/starlight/components';
import { Badge } from '@astrojs/starlight/components';

Run Knip as you normally would, and if the report looks good then run it again
with the --fix flag to let Knip automatically apply fixes. It fixes the
following issue types:

• Remove unused files
• Remove export keyword for unused exports, re-exports, and exported types
• Remove export default keywords for unused default exports
• Remove unused enum and namespace members
• Remove unused dependencies and devDependencies from package.json
• Remove unused catalog entries

:::caution

Use a VCS (version control system) like Git to review and undo changes as
necessary.

:::

Flags Copy Chapter

Fix Copy Section

Add the --fix flag to remove unused exports and dependencies:

knip --fix

Add --allow-remove-files to allow Knip to remove unused files:

knip --fix --allow-remove-files

Use --fix-type to fix only specific issue types:

• dependencies
• exports
• types
• files
• catalog

Example:

knip --fix-type exports,types
knip --fix-type exports --fix-type types   # same as above

Format Copy Section

Add --format to format the modified files using the formatter and
configuration in your project. Supports Biome, deno fmt, dprint and Prettier
(using Formatly):

knip --fix --format

Demo Copy Chapter

Post-fix Copy Chapter

After Knip has fixed issues, there are four things to consider:

1. Use a formatter Copy Section

Use a tool like Prettier or Biome if the code needs formatting. Knip removes the
minimum amount of code while leaving it in a working state.

:::tip

Add the --format flag to format the modified files using the formatter and
configuration in your project.

:::

2. Unused variables Copy Section

Use a tool like ESLint or Biome to find and remove unused imports and variables
inside files. Even better, try remove-unused-vars to remove unused
variables within files.

This may result in more deleted code, and Knip may then find more unused code.
Rinse and repeat!

3. Unused dependencies Copy Section

Verify changes in package.json and update dependencies using your package
manager.

4. Install unlisted dependencies Copy Section

If Knip reports unlisted dependencies or binaries, they should be installed
using the package manager in the project, for example:

Example results Copy Chapter

Exports Copy Section

The export keyword for unused exports is removed:

-export const unused = 1;
-export default class MyClass {}
+const unused = 1;
+class MyClass {}

The default keyword was also removed here.

Knip removes the whole or part of export declarations:

type Snake = 'python' | 'anaconda';
const Owl = 'Hedwig';
const Hawk = 'Tony';
-export type { Snake };
-export { Owl, Hawk };
+;
+;

Re-exports Copy Section

Knip removes the whole or part of re-exports:

-export { Cat, Dog } from './pets';
-export { Lion, Elephant } from './jungle';
+export { Elephant } from './jungle'

Also across any chain of re-exports:

Export assignments Copy Section

Knip removes individual exported items in "export assignments", but does not
remove the entire export declaration if it's empty:

-export const { a, b  } = fn();
+export const {   } = fn();

-export const [c, d] = [c, d];
+export const [, ] = [c, d];

Reason: the right-hand side of the assignment might have side-effects. It's not
safe to always remove the whole declaration. This could be improved in the
future (feel free to open an issue/RFC).

Enum members Copy Section

Unused members of enums are removed:

export enum Directions {
  North = 1,
  East = 2,
-  South = 3,
  West = 4,
}

CommonJS Copy Section

Knip supports CommonJS and removes unused exports:

-module.exports = { identifier, unused };
+module.exports = { identifier,  };

-module.exports.UNUSED = 1;
-module.exports['ACCESS'] = 1;
+
+

Warning: the right-hand side of such an assignment might have side-effects. Knip
currently removes the whole declaration (feel free to open an issue/RFC).

Dependencies Copy Section

Unused dependencies are removed from package.json:

{
   "name": "my-package",
   "dependencies": {
-    "rimraf": "*",
-    "unused-dependency": "*"
+    "rimraf": "*"
   },
-  "devDependencies": {
-    "unreferenced-package": "5.3.3"
-  }
+  "devDependencies": {}
 }

Catalog entries Copy Section

Unused catalog entries are removed from pnpm-workspace.yaml:

packages:
   - 'packages/*'
 catalog:
   react: ^18.0.0
-  unused-package: ^1.0.0

Catalogs in package.json are supported as well.

What's not included Copy Chapter

Operations that auto-fix does not (yet) perform and why:

• Add unlisted (dev) dependencies to package.json (should it go into
  dependencies or devDependencies? For monorepos in current workspace or
  root?)
• Add unlisted binaries (which package and package version contains the used
  binary?)
• Fix duplicate exports (which one should be removed?)

Packages Docs Src Content Docs Features Catalogs (`packages/docs/src/content/docs/features/catalogs.md`) Copy Section

title: Catalogs Copy Chapter

Catalogs let you define dependency version ranges once and reference them across
workspaces in a monorepo. Knip reports catalog entries that are defined but no
longer referenced, and references to entries that do not exist. It can remove
unused entries with auto-fix.

Supported catalogs Copy Chapter

Knip reads catalogs from the first applicable location:

• pnpm-workspace.yaml — the catalog (default) and catalogs (named) keys
• .yarnrc.yml — the catalog and catalogs keys
• package.json — the catalog and catalogs keys
• package.json#workspaces — the catalog and catalogs keys (Bun)

Unused catalog entries Copy Chapter

A catalog entry is reported as unused when no workspace references it through
the catalog: protocol in its package.json:

{
  "dependencies": {
    "react": "catalog:",
    "zod": "catalog:validation"
  }
}

catalog: references the default catalog, while catalog:validation
references the named validation catalog. References are resolved from
dependencies, devDependencies, peerDependencies, optionalDependencies,
resolutions, pnpm-workspace.yaml#overrides, and pnpm.overrides in the root
package.json (pnpm 10 and older).

Entries defined in a catalog but not referenced anywhere are reported as unused
catalog entries.

Unresolved catalog references Copy Chapter

A catalog: reference is reported when the selected catalog does not define
that package. These issues point to the consuming package.json or
pnpm-workspace.yaml, where package managers would otherwise fail to resolve
the version.

Filter and fix Copy Chapter

The catalog and catalogReferences issue types are included by the
--dependencies shortcut. Focus on them (or exclude them) like any other
issue type:

knip --include catalog,catalogReferences
knip --exclude catalog,catalogReferences

Auto-fix removes unused catalog entries from the catalog file:

knip --fix --fix-type catalog

Packages Docs Src Content Docs Features Compilers (`packages/docs/src/content/docs/features/compilers.md`) Copy Section

title: Compilers Copy Chapter

Projects may have source files that are not JavaScript or TypeScript, and thus
require compilation (or transpilation, or pre-processing, you name it). Files
like .mdx, .astro, .vue and .svelte may also import other source files
and external dependencies. So ideally, these files are included when linting the
project. That's why Knip supports compilers.

Built-in compilers Copy Chapter

Knip has built-in "compilers" for the following file extensions:

• .astro
• .css (only enabled by tailwindcss)
• .mdx
• .prisma
• .sass + .scss
• .less
• .styl + .stylus
• .svelte
• .tsrx
• .vue

Knip does not include real compilers for those files, but regular expressions to
collect import statements. This is fast, requires no dependencies, and enough
for Knip to build the module graph. The tradeoff is that unused exports inside
these files go unreported.

Real compilers recover those exports, but bring their own challenges. The Svelte
compiler, for instance, keeps exports intact even when they represent
component properties, so Knip reports them as unused. When you need that
fidelity, override any built-in with the framework's own compiler (see the
Svelte and Vue examples below). For example, to report unused exports
in .tsrx files.

Compilers are enabled only when a related dependency is found. The .tsrx
compiler when a @tsrx/* package is installed, for example. If that detection
doesn't work for your project, set true to enable any compiler manually:

export default {
  compilers: {
    mdx: true,
  },
};

Compiled files and `project` patterns Copy Chapter

The default project patterns include compiler extensions automatically. When
you override project, list them explicitly:

export default {
  project: ['src/**/*.{ts,tsx,css}'],
};

Files outside project are not analyzed, so their imports don't count. A
narrowed pattern like ['src/**/*.{ts,tsx}'] silently drops everything a
stylesheet imports, which is a common source of false positives: @import 'tailwindcss' in an excluded .css file gets tailwindcss reported as an
unused dependency. Knip reports a configuration hint when a compiled extension
is excluded this way.

Custom compilers Copy Chapter

Built-in compilers can be overridden, and additional compilers can be added.
Since compilers are functions, the Knip configuration file must be a dynamic
.js or .ts file.

Interface Copy Section

The compiler function interface is straightforward. Text in, text out:

(source: string, filename: string) => string | PromiseLike<string>;

Return a string or a Promise-like value that resolves to a string. Knip compiles
files on demand and awaits asynchronous results; the async keyword is
optional.

Examples Copy Section

• CSS
• MDX
• Svelte
• Vue

CSS

Here's an example, minimal compiler for CSS files:

export default {
  compilers: {
    css: (text: string) => [...text.matchAll(/(?<=@)import[^;]+/g)].join('\n'),
  },
};

You may wonder why the CSS compiler is not included by default. It's currently
not clear if it should be included. And if so, what would be the best way to
determine it should be enabled, and what syntax(es) it should support. Note that
Tailwind CSS, SASS/SCSS, Less and Stylus compilers are included.

MDX

Another example, in case the built-in MDX compiler is not enough:

import { compile } from '@mdx-js/mdx';

export default {
  compilers: {
    mdx: async text => (await compile(text)).toString(),
  },
};

Svelte

In a Svelte project, the compiler is automatically enabled. Override and use
Svelte's compiler for better results if the built-in "compiler" is not enough:

import type { KnipConfig } from 'knip';
import { compile } from 'svelte/compiler';

export default {
  compilers: {
    svelte: (source: string) => compile(source, {}).js.code,
  },
} satisfies KnipConfig;

Vue

In a Vue project, the compiler is automatically enabled. Override and use Vue's
parser for better results if the built-in "compiler" is not enough:

import type { KnipConfig } from 'knip';
import {
  parse,
  type SFCScriptBlock,
  type SFCStyleBlock,
} from 'vue/compiler-sfc';

function getScriptBlockContent(block: SFCScriptBlock | null): string[] {
  if (!block) return [];
  if (block.src) return [`import '${block.src}'`];
  return [block.content];
}

function getStyleBlockContent(block: SFCStyleBlock | null): string[] {
  if (!block) return [];
  if (block.src) return [`@import '${block.src}';`];
  return [block.content];
}

function getStyleImports(content: string): string {
  return [...content.matchAll(/(?<=@)import[^;]+/g)].join('\n');
}

const config = {
  compilers: {
    vue: (text: string, filename: string) => {
      const { descriptor } = parse(text, { filename, sourceMap: false });
      return [
        ...getScriptBlockContent(descriptor.script),
        ...getScriptBlockContent(descriptor.scriptSetup),
        ...descriptor.styles.flatMap(getStyleBlockContent).map(getStyleImports),
      ].join('\n');
    },
  },
} satisfies KnipConfig;

export default config;

Tracking non-source files Copy Chapter

To track any file extension that's not meant to compile to JavaScript, register
a no-op compiler:

export default {
  compilers: { template: () => '' },
};

Packages Docs Src Content Docs Features Custom Elements (`packages/docs/src/content/docs/features/custom-elements.md`) Copy Section

title: Custom Elements Copy Chapter

Custom elements are registered under a tag name. When such a class isn't
referenced elsewhere, Knip would report the export as unused. Instead, Knip
recognizes the registration and considers the class used.

Native registration needs no configuration. Framework registrations are credited
through their plugin, which is enabled when the framework is a dependency.

Native registration Copy Chapter

The web standard customElements.define() credits the registered class:

export class MyCard extends HTMLElement {}

customElements.define('my-card', MyCard);

The registry can be the global customElements — directly, through a window,
globalThis or self prefix, or a local alias — a CustomElementRegistry
instance, or a shadow root's scoped registry:

const registry = new CustomElementRegistry();
registry.define('my-card', MyCard);

A class can also register itself from a static block using this:

export class MyCard extends HTMLElement {
  static {
    customElements.define('my-card', this);
  }
}

Framework registration Copy Chapter

The decorator counts only when imported from the framework. A locally defined or
differently-imported decorator is ignored.

Lit Copy Section

A @customElement('tag') decorator credits the class when the matching plugin
is enabled:

import { LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('my-card')
export class MyCard extends LitElement {}

FAST Copy Section

FAST also registers elements through a static define() or defineAsync()
method. A class extending FASTElement, directly or through a mixin, is
credited when registered this way:

import { FASTElement } from '@microsoft/fast-element';

export class MyCard extends FASTElement {}

MyCard.define('my-card');

Stencil Copy Section

A @Component decorator credits the class:

import { Component } from '@stencil/core';

@Component({ tag: 'my-card' })
export class MyCard {}

Catalyst Copy Section

The bare @controller decorator registers the element under a tag derived from
the class name:

import { controller } from '@github/catalyst';

@controller
export class MyCardElement extends HTMLElement {}

Packages Docs Src Content Docs Features Integrated Monorepos (`packages/docs/src/content/docs/features/integrated-monorepos.md`) Copy Section

title: Integrated Monorepos Copy Chapter

Some repositories have a single package.json, but consist of multiple projects
with configuration files across the repository. A good example is the Nx
integrated monorepo style.

:::tip

An integrated monorepo is a single workspace.

:::

Entry Files Copy Chapter

The default entrypoints files might not be enough. Here's an idea that might fit
this type of monorepo:

{
  "entry": ["{apps,libs}/**/src/index.{ts,tsx}"],
  "project": ["{apps,libs}/**/src/**/*.{ts,tsx}"]
}

Plugins Copy Chapter

Let's assume some of these projects are applications ("apps") which have their
own ESLint configuration files and Cypress configuration and test files. This
may result in those files getting reported as unused, and consequently also the
dependencies they import and refer to.

In that case, we could configure the ESLint and Cypress plugins like this:

{
  "eslint": {
    "config": ["{apps,libs}/**/.eslintrc.json"]
  },
  "cypress": {
    "entry": ["apps/**/cypress.config.ts", "apps/**/cypress/e2e/*.spec.ts"]
  }
}

Adapt the file patterns to your project, and the relevant config and entry
files and dependencies should no longer be reported as unused.

Internal Workspace Dependencies Copy Chapter

A note about repositories with multiple package.json files and internal
workspace packages: it is recommended to list all dependencies in each consuming
package.json, allowing Knip to do fine-grained reporting of both unused and
unlisted dependencies.

An alternative is to ignoreDependencies: ["@internal/*"].

Packages Docs Src Content Docs Features Monorepos And Workspaces (`packages/docs/src/content/docs/features/monorepos-and-workspaces.md`) Copy Section

title: Monorepos & Workspaces Copy Chapter

Workspaces are handled out-of-the-box by Knip.

Workspaces are sometimes also referred to as package-based monorepos, or as
packages in a monorepo. Knip uses the term workspace exclusively to indicate a
directory that has a package.json.

Configuration Copy Chapter

Here's example configuration with custom entry and project patterns:

{
  "workspaces": {
    ".": {
      "entry": "scripts/*.js",
      "project": "scripts/**/*.js"
    },
    "packages/*": {
      "entry": "{index,cli}.ts",
      "project": "**/*.ts"
    },
    "packages/cli": {
      "entry": "bin/cli.js"
    }
  }
}

:::tip

Run Knip without any configuration to see if and where custom entry and/or
project files are necessary per workspace.

:::

Each workspace has the same default configuration.

The root workspace is named "." under workspaces (like in the example
above).

:::caution

In a project with workspaces, the entry and project options at the root
level are ignored. Use the workspace named "." for those (like in the example
above).

:::

Workspaces Copy Chapter

Knip reads workspaces from four possible locations:

1. The workspaces array in package.json (npm, Bun, Yarn, Lerna)
2. The packages array in pnpm-workspace.yaml (pnpm)
3. The workspaces.packages array in package.json (legacy)
4. The workspaces object in Knip configuration

The workspaces in Knip configuration (4) not already defined in the root
package.json or pnpm-workspace.yaml (1, 2, 3) are added to the analysis.

:::caution

A workspace must have a package.json file.

:::

For projects with only a root package.json, please see integrated
monorepos.

Additional workspaces Copy Chapter

If a workspace is not configured as such in package.json#workspaces (or
pnpm-workspace.yaml) it can be added to the Knip configuration manually. Add
their path to the workspaces configuration object the same way as
"packages/cli": {} in the example above.

Source mapping Copy Chapter

See Source Mapping.

Additional options Copy Chapter

The following options are available inside workspace configurations:

• ignore
• ignoreBinaries
• ignoreDependencies
• ignoreIssues
• ignoreMembers
• ignoreUnresolved
• includeEntryExports

Plugins can be configured separately per workspace.

Use --debug for verbose output and see the workspaces Knip includes, their
configurations, enabled plugins, glob options and resolved files.

Filter workspaces Copy Chapter

Use the --workspace (or -W) argument to select one or more workspaces:

knip --workspace packages/my-lib

The filter supports multiple formats:

knip --workspace @myorg/my-lib     # Package name
knip --workspace '@myorg/*'        # Package name glob
knip --workspace packages/my-lib   # Directory path
knip --workspace './apps/*'        # Directory glob

Combine selectors to include or exclude workspaces:

knip --workspace @myorg/* --workspace '!@myorg/legacy'
knip --workspace './apps/*' --workspace '@shared/utils'

This will include the target workspace(s), but also ancestor, dependency and
dependent workspaces. For three reasons:

• Ancestor workspaces may list dependencies in package.json the linted
  workspace uses.
• Dependency workspaces may provide configuration and source information used by
  the linted workspace.
• Dependent workspaces may reference exports from the linted workspace.

To lint the workspace in isolation, there are two options:

• Combine the workspace argument with strict production mode.
• Run Knip from inside the workspace directory.

Packages Docs Src Content Docs Features Production Mode (`packages/docs/src/content/docs/features/production-mode.md`) Copy Section

title: Production Mode Copy Chapter

The default mode for Knip is comprehensive and targets all project code,
including configuration files, test files, Storybook stories, and so on. Test
files usually import production files. This prevents production files or their
exports from being reported as unused, while sometimes both of them can be
deleted. Knip features a "production mode" to focus only on the code that you
ship.

Configuration Copy Chapter

To tell Knip what is production code, add an exclamation mark behind each
pattern! that represents production code:

{
  "entry": ["src/index.ts!", "build/script.js"],
  "project": ["src/**/*.ts!", "build/*.js"]
}

Depending on file structure and enabled plugins, you might not need to modify
your configuration at all.

Run Knip with the --production flag:

knip --production

Here's what's included in production mode:

• Only entry and project patterns suffixed with !
• Only production entry file patterns exported by plugins (such as Next.js and
  Remix)
• Only the start script (of package.json#scripts)
• Ignore exports with the @internal tag

:::note

The production run does not replace the default run. Depending on your needs you
can run either of them or both separately. Usually both modes can share the same
configuration.

:::

To see the difference between default and production mode in great detail, use
the --debug flag and inspect what entry and project files are used, and the
plugins that are enabled. For instance, in production mode this shows that files
such as tests and Storybook files (stories) are excluded from the analysis.

In case files like mocks and test helpers are reported as unused files, use
negated patterns to exclude those files in production mode:

{
  "entry": ["src/index.ts!"],
  "project": ["src/**/*.ts!", "!src/test-helpers/**!"]
}

Also see configuring project files to align entry and project with
production mode.

Strict Mode Copy Chapter

In production mode, only dependencies (not devDependencies) are considered
when finding unused or unlisted dependencies.

Additionally, the --strict flag can be added to:

• Verify isolation: workspaces should use strictly their own dependencies
• Include required peerDependencies when finding unused or unlisted
  dependencies
• Distinguish development-only type imports from types exposed to package
  consumers

knip --production --strict

Using --strict implies --production, so the latter can be omitted.

Types Copy Chapter

Add --exclude types if you don't want to include types in the report:

knip --production --exclude types

Packages Docs Src Content Docs Features Reporters (`packages/docs/src/content/docs/features/reporters.md`) Copy Section

title: Reporters & Preprocessors Copy Chapter

Built-in Reporters Copy Chapter

Knip provides the following built-in reporters:

• codeclimate
• codeowners
• compact
• cycles
• disclosure
• github-actions
• json
• markdown
• sarif
• symbols (default)

Example usage:

knip --reporter compact

CodeClimate Copy Section

The built-in codeclimate reporter generates output in the Code Climate Report
JSON format. Example usage:

$ knip --reporter codeclimate

[
  {
    "type": "issue",
    "check_name": "Unused exports",
    "description": "isUnused",
    "categories": ["Bug Risk"],
    "location": {
      "path": "path/to/file.ts",
      "positions": {
        "begin": {
          "line": 6,
          "column": 1
        }
      }
    },
    "severity": "major",
    "fingerprint": "e9789995c1fe9f7d75eed6a0c0f89e84"
  }
]

CODEOWNERS Copy Section

When a .github/CODEOWNERS file exists, each entry gains an owners array.
Point the reporter at a different path through --reporter-options:

knip --reporter json --reporter-options '{"codeowners":"docs/CODEOWNERS"}'

Cycles Copy Section

A verbose, multi-line tree view of circular dependencies. Each file path
is suffixed with the location of the import that continues the cycle. Each edge
shows the import kind and specifier, descends one file per level, and closes
(↩) back to the file it started from.

Use --cycles to report only circular dependencies and --reporter cycles to
display them as a tree:

$ knip --cycles --reporter cycles

Circular dependencies (1)

src/i18n/index.ts:1:28
└── import ./middleware → src/i18n/middleware.ts:3:15
    └── re-export ../core/i18n/handler → src/core/i18n/handler.ts:5:10
        └── import ../../i18n → src/i18n/index.ts:1:28 ↩

Knip reports representative cycle paths found while walking the module graph.
This is not an exhaustive list of every possible simple cycle in a cyclic
subgraph, because that can produce a noisy and very large report. If the same
file participates in multiple distinct reported paths, each path is shown
separately.

Use cycles.allow to accept known cycle paths.

Dynamic imports are ignored by default because they are commonly used to avoid
synchronous circular loads. Set cycles.dynamicImports to include them.
Repeated starting imports are grouped under one heading.

For one line per cycle path, use knip --cycles with the default reporter. To
report unused code as well, combine the issue-type shorthands.

Cycles are warnings by default. Set "rules": { "cycles": "error" } to make
reported cycles cause a non-zero exit code.

Disclosure Copy Section

This reporter is useful for sharing large reports. Groups of issues are rendered
in a closed state initially. The reporter renders this:

$ knip --reporter disclosure

<details>
<summary>Unused files (2)</summary>

```
unused.ts
dangling.js
```

</details>

<details>
<summary>Unused dependencies (2)</summary>

```
my-package     package.json:17:5
unused-dep     package.json:20:5
```

</details>

The above can be copy-pasted where HTML and Markdown is supported, such as a
GitHub issue or pull request, and renders like so:

Unused files (2)

unused.ts
dangling.js

Unused dependencies (2)

my-package     package.json:17:5
unused-dep     package.json:20:5

GitHub Actions Copy Section

Use the GitHub Actions reporter in a workflow for annotations in pull requests.
Example usage:

knip --reporter github-actions

Changed files in pull requests will now contain inline annotations for lint
findings.

JSON Copy Section

The json reporter prints machine-readable results for scripts, CI, and tools
(including coding agents) to consume:

knip --reporter json

Output is one line of JSON. Formatted here for readability:

{
  "issues": [
    {
      "file": "src/legacy.ts",
      "files": [{ "name": "src/legacy.ts" }]
    },
    {
      "file": "src/math.ts",
      "exports": [{ "name": "factorial", "line": 12, "col": 14, "pos": 256 }],
      "types": [{ "name": "Radians", "line": 20, "col": 13, "pos": 410 }]
    },
    {
      "file": "package.json",
      "dependencies": [{ "name": "lodash" }],
      "unlisted": [{ "name": "rimraf" }]
    }
  ]
}

The top level is an object with a single issues array. Each element groups
every issue found in one file:

Each entry carries a key for every enabled issue type, so the keys are
the same across entries. An array is empty when that file has no issues of that
type. Drop a type's key by disabling it with filters or rules.

Issue-type items are objects with position info:

See Issue types for the full set of issue-type keys.

For a typed object instead of JSON to parse, write a custom reporter.
Coding agents can also call Knip through the MCP server, which returns
structured results and configuration hints directly.

SARIF Copy Section

The sarif reporter emits SARIF 2.1.0 for code-scanning integrations:

knip --reporter sarif > knip.sarif

For example, upload the report to GitHub Code Scanning after installing project
dependencies:

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v4
  - run: pnpm exec knip --reporter sarif > knip.sarif
  - if: always()
    uses: github/codeql-action/upload-sarif@v4
    with:
      sarif_file: knip.sarif

The upload step runs even when Knip finds issues and exits non-zero. GitHub Code
Scanning availability for private repositories depends on the repository's
GitHub Code Security plan.

Markdown Copy Section

The built-in markdown reporter output is meant to be saved to a Markdown file.
This allows following the changes in issues over time. It reports issues in
Markdown tables separated by issue types as headings, for example:

# Knip report

## Unused files (1)

- src/unused.ts

## Unlisted dependencies (2)

| Name            | Location          | Severity |
| :-------------- | :---------------- | :------- |
| unresolved      | src/index.ts:8:23 | error    |
| @org/unresolved | src/index.ts:9:23 | error    |

## Unresolved imports (1)

| Name         | Location           | Severity |
| :----------- | :----------------- | :------- |
| ./unresolved | src/index.ts:10:12 | error    |

Custom Reporters Copy Chapter

When the provided built-in reporters are not sufficient, a custom local reporter
can be implemented or an external reporter can be used. Multiple reporters can
be used at once by repeating the --reporter argument.

The results are passed to the function from its default export and can be used
to write issues to stdout, a JSON or CSV file, or sent to a service. It
supports a local JavaScript or TypeScript file or an external dependency.

Local Copy Section

The default export of the reporter should be a function with this interface:

type Reporter = (options: ReporterOptions) => void;

type ReporterOptions = {
  report: Report;
  issues: Issues;
  counters: Counters;
  configurationHints: ConfigurationHints;
  isDisableConfigHints: boolean;
  isTreatConfigHintsAsErrors: boolean;
  cwd: string;
  isProduction: boolean;
  isShowProgress: boolean;
  options: string;
};

The data can then be used to write issues to stdout, a JSON or CSV file, or
sent to a service.

Here's a most minimal reporter example:

import type { Reporter } from 'knip';

const reporter: Reporter = function (options) {
  console.log(options.issues);
  console.log(options.counters);
};

export default reporter;

Example usage:

knip --reporter ./my-reporter.ts

External Copy Section

Pass --reporter [pkg-name] to use an external reporter. The default exported
function of the main script (default: index.js) will be invoked with the
ReporterOptions, just like a local reporter.

Preprocessors Copy Chapter

A preprocessor is a function that runs after the analysis is finished. It
receives the results from the analysis and should return data in the same
shape/structure (unless you pass it to only your own reporter).

The data goes through the preprocessors before the final data is passed to the
reporters. There are no built-in preprocessors. Just like reporters, use e.g.
--preprocessor ./my-preprocessor from the command line (can be repeated).

The default export of the preprocessor should be a function with this interface:

type Preprocessor = (options: ReporterOptions) => ReporterOptions;

Like reporters, you can use local JavaScript or TypeScript files and external
npm packages as preprocessors.

Example preprocessor:

import type { Preprocessor } from 'knip';

const preprocess: Preprocessor = function (options) {
  // modify options.issues and options.counters
  return options;
};

export default preprocess;

Example usage:

knip --preprocessor ./preprocess.ts

Preprocessors can also be configured in the Knip configuration file:

{
  "preprocessor": "./preprocess.ts"
}

Packages Docs Src Content Docs Features Rules And Filters (`packages/docs/src/content/docs/features/rules-and-filters.md`) Copy Section

title: Rules & Filters Copy Chapter

Use rules or filters to customize Knip's output. This has various use cases, a
few examples:

• Temporarily focus on a specific issue type.
• You don't want to see unused type, interface and enum exports reported.
• Specific issue types should be printed, but not counted against the total
  error count.

If you're looking to handle one-off exceptions, also see JSDoc tags.

Filters Copy Chapter

You can --include or --exclude any of the reported issue types to slice &
dice the report to your needs. Alternatively, they can be added to the
configuration (e.g. "exclude": ["dependencies"]).

Use --include to report only specific issue types. The following example
commands do the same:

knip --include files --include dependencies
knip --include files,dependencies

Or the other way around, use --exclude to ignore the types you're not
interested in:

knip --include files --exclude enumMembers,duplicates

The nsExports and nsTypes types are off by default. Including only
those adds them to the default report, rather than narrowing it to just those.

cycles is also off by default. --include cycles (or "include": ["cycles"]
in configuration) reports only circular dependencies. Use it with the cycles
reporter for a detailed tree view.

Also see the list of issue types.

Shorthands Copy Section

Knip has shortcuts to report only specific issue types.

1. The --dependencies flag includes:

   • dependencies (and devDependencies + optionalPeerDependencies)
   • unlisted
   • binaries
   • unresolved
   • catalog
   • catalogReferences

2. The --exports flag includes:

   • exports
   • types
   • enumMembers
   • namespaceMembers
   • duplicates

3. The --files flag is a shortcut to report only unused files.

4. The --cycles flag is a shortcut to report only circular dependencies.

Combine shorthands to report the default issue types plus circular dependencies:

knip --dependencies --exports --files --cycles

Rules Copy Chapter

Use rules in the configuration to customize the issue types that count towards
the total error count, or to exclude them altogether.

Example:

{
  "rules": {
    "files": "warn",
    "duplicates": "off"
  }
}

Notes:

• ¹ Exception: the cycles issue type is a warning by default.
• If the dependencies issue type is included, the devDependencies and
  optionalPeerDependencies types can still be set to "warn" separately.
• The rules are modeled after the ESLint rules configuration, and could be
  extended in the future.

Also see the issue types overview.

Rules or filters? Copy Chapter

Filters are meant to be used as command-line flags, rules allow for more
fine-grained configuration.

• Rules are more fine-grained since they also have "warn".
• Rules could be extended in the future.
• Filters can be set in configuration and from CLI (rules only in
  configuration).
• Filters have shorthands (rules don't have this).

Packages Docs Src Content Docs Features Script Parser (`packages/docs/src/content/docs/features/script-parser.md`) Copy Section

title: Script Parser Copy Chapter

Knip parses shell commands and scripts to find additional dependencies, entry
files and configuration files in various places:

• In package.json
• In CLI arguments
• In scripts
• In source code

Shell scripts are parsed and statically analyzed, but they're not executed.

package.json Copy Chapter

The main, bin, exports and scripts fields may contain entry files. Let's
take a look at this example:

{
  "name": "my-package",
  "main": "index.js",
  "exports": {
    "./lib": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "bin": {
    "program": "bin/cli.js"
  },
  "scripts": {
    "build": "rollup src/entry.ts",
    "start": "node --loader tsx server.ts"
  }
}

From this example, Knip automatically adds the following files as entry files:

• index.js
• ./dist/index.mjs
• ./dist/index.cjs
• bin/cli.js
• src/entry.ts
• server.ts

Excluded files Copy Section

Knip would not add the exports if the dist folder is matching a pattern in a
relevant .gitignore file or ignore option.

Knip does not add scripts without a standard extension. For instance, the
bin/tool file might be a valid executable for Node.js, but wouldn't be added
or parsed by Knip.

CLI Arguments Copy Section

When parsing the scripts of package.json and other files, Knip detects
various types of inputs. Some examples:

• The first positional argument is usually an entry file
• Configuration files are often in the -c or --config argument
• The --require, --loader or --import arguments are often dependencies

{
  "name": "my-lib",
  "scripts": {
    "start": "node --import tsx/esm run.ts",
    "bundle": "tsup -c tsup.lib.config.ts",
    "type-check": "tsc -p tsconfig.app.json"
  }
}

The "start" script will have tsx marked as a referenced dependency, and adds
run.ts as an entry file.

Additionally, the following files are detected as configuration files:

• tsup.lib.config.ts - to be handled by the tsup plugin
• tsconfig.app.json - to be handled by the TypeScript plugin

Such executables and their arguments are all defined in plugins separately for
fine-grained results.

Scripts Copy Chapter

Plugins may also use the script parser to extract entry files and dependencies
from commands. A few examples:

• GitHub Actions: workflow files may contain run commands (e.g.
  .github/workflows/ci.yml)
• Husky & Lefthook: Git hooks such as .git/hooks/pre-push contain scripts;
  also lefthook.yml has run commands
• Lint Staged: configuration values are all commands
• Nx: task executors and nx:run-commands executors in project.json contains
  scripts
• Release It: hooks contain commands

Plugins can also return configuration files. Some examples:

• The Angular plugin detects options.tsConfig as a TypeScript config file
• The GitHub Actions plugin parses run commands which may contain
  configuration file paths

Source Code Copy Chapter

When Knip is walking the abstract syntax trees (ASTs) of JavaScript and
TypeScript source code files, it looks for imports and exports. But there's a
few more (rather obscure) things that Knip detects in the process. Below are
examples of additional scripts Knip parses to find entry files and dependencies.

bun Copy Section

If the bun dependency is imported in source code, Knip considers the contents
of $ template tags to be scripts:

import { $ } from 'bun';
await $`bun boxen I ❤ unicorns`;
await $`boxen I ❤ unicorns`;

Parsing the script results in the boxen binary (the boxen-cli dependency) as
referenced (twice).

execa Copy Section

If the execa dependency is imported in source code, Knip considers the
contents of $ template tags to be scripts:

await $({ stdio: 'inherit' })`c8 node hydrate.js`;

Parsing the script results in hydrate.js added as an entry file and the c8
binary/dependency as referenced. The execa(), execaSync(), execaCommand()
and execaCommandSync() call forms are parsed the same way.

zx Copy Section

If the zx dependency is imported in source code, Knip considers the contents
of $ template tags to be scripts:

await $`node scripts/parse.js`;

This will add scripts/parse.js as an entry file.

child\_process Copy Section

If node:child_process is imported in source code, Knip parses the command in
exec/execSync calls and the executable (with its arguments) in
spawn/spawnSync/execFile/execFileSync calls:

import { execSync, execFile } from 'node:child_process';
execSync('eslint --cache');
execFile('boxen', ['I ❤ unicorns']);

This marks the eslint and boxen binaries as referenced. An inline
path.join(__dirname, …) argument to spawn, execFile or fork is added as
an entry file instead.

nano-spawn Copy Section

If nano-spawn is imported in source code, Knip parses the executable and its
arguments:

import spawn from 'nano-spawn';
await spawn('gsutil', ['cp', './file.txt', 'gs://bucket/']);

This marks the gsutil binary as referenced.

Packages Docs Src Content Docs Features Source Mapping (`packages/docs/src/content/docs/features/source-mapping.md`) Copy Section

title: Source Mapping Copy Chapter

Knip is mostly interested in source code. Analyzing build artifacts hurts
performance and often leads to false positives, as they potentially contain
bundled code and unresolvable imports.

That's why Knip tries to map such build artifacts back to their original source
files and analyze those instead. This is done based on tsconfig.json settings.

Example 1: package.json Copy Chapter

Let's look at an example case with package.json and tsconfig.json files, and
see how "dist" files are mapped to "src" files.

{
  "name": "my-workspace",
  "main": "index.js",
  "exports": {
    ".": "./src/entry.js",
    "./feat": "./lib/feat.js",
    "./public": "./dist/app.js",
    "./public/*": "./dist/*.js",
    "./public/*.js": "./dist/*.js",
    "./dist/internal/*": null,
  },
}

With this TypeScript configuration:

{
  "compilerOptions": {
    "baseUrl": "src",
    "outDir": "dist"
  }
}

• ./src/entry.js is not in an outDir folder, so it's added as an entry file
• ./lib/feat.js is not in an outDir folder, so it's added as an entry file
• ./dist/app.js is in a dist folder and mapped to ./src/app.{js,ts} (¹)
• ./dist/*.js is in a dist folder and mapped to ./src/**/*.{js,ts} (¹)
• ./dist/internal/* is translated to ./dist/internal/** and files in this
  directory and deeper are ignored when globbing entry files

(¹) full extensions list is actually: js, mjs, cjs, jsx, ts, tsx,
mts, cts

In --debug mode, look for "Source mapping" to see this in action.

:::tip

Using ./dist/*.js means that all files matching ./src/**/*.{js,ts} are added
as entry files. By default, unused exports of entry files are not reported. Use
includeEntryExports to include them.

:::

Example 2: monorepo Copy Chapter

Let's say we have this module in a monorepo that imports helper from another
workspace in the same monorepo:

import { helper } from '@org/shared';

The target workspace @org/shared has this package.json:

{
  "name": "@org/shared",
  "main": "dist/index.js"
}

The module resolver will resolve @org/shared to dist/index.js. That file is
usually compiled and git-ignored, while Knip wants the source file instead.

:::tip

You may need to compile build artifacts to outDir first before Knip can
successfully apply source mapping for internal references in a monorepo.

:::

If the target workspace has a tsconfig.json file with an outDir option, Knip
will try to map the "dist" file to the "src" file. Then if src/index.ts
exists, Knip will use that file instead of dist/index.js.

Currently this only works based on tsconfig.json, in the future more source
mappings may be added.

Example 3: source conditions Copy Chapter

Source-first monorepos may expose source files directly through a custom
condition in package.json#exports or #imports maps:

{
  "name": "@org/shared",
  "exports": {
    ".": {
      "@org/source": "./src/index.ts",
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  }
}

When module resolution fails because the targets aren't built, Knip falls back
to the first conditional target of the workspace package that exists on disk,
regardless of the condition's name. No build step or configuration required.

Packages Docs Src Content Docs Guides Adopt Gradually (`packages/docs/src/content/docs/guides/adopt-gradually.md`) Copy Section

title: Adopt Knip gradually Copy Chapter

On a large or legacy codebase the first run can report a lot. Reaching zero in
one sitting is then the wrong goal. Get a trustworthy signal first, then ratchet
the codebase toward clean and keep it there.

Actionable baseline Copy Chapter

Most of the noise on a first run comes from gaps in what Knip can reach: a
dependency that Knip does not have a plugin for yet, an entry point it can't
resolve, a phantom dependency. Fix the gaps before you delete anything:

• Address configuration hints.
• Tune entry and project files so Knip analyzes the right set of files.
• Tune configuration for your tools' plugins.

Read the output from the top. One unused file hides its exports and
dependencies, so files come first.

Once the report reflects real findings instead of gaps, you have an actionable
baseline.

Focus one issue type at a time Copy Chapter

Don't fix everything at once. Narrow the report with filters:

knip --files        # unused files only (the major cascade!)
knip --dependencies # then dependencies
knip --exports      # then exports and types

Clear one type, commit, move to the next.

Stage by rules Copy Chapter

Rules set a severity per issue type. Start by setting all types to
"warn", and then the types you've cleaned to "error". Warnings are printed
in gray, and they don't fail the run. Example:

{
  "rules": {
    "files": "error",
    "dependencies": "error",
    "exports": "warn",
    "duplicates": "off"
  }
}

As each "warn" type reaches zero, set it to "error". Keep iterating and
prune the codebase to perfection.

Gate CI without blocking the team Copy Chapter

Add Knip to CI as soon as you have a baseline, so new clutter is caught in
review. A few ways to stage it:

• Mark cleaned types "error" and the rest "warn", so CI fails only on the
  types you've finished.
• Workspace by workspace: in a monorepo, scope passes with --workspace
  (accepts multiple workspaces and glob patterns).
• Production first: --production limits analysis to shipped code, so you
  can clean what matters most and defer tests and tooling.
• Set a budget, so CI fails only when the count exceeds the number (e.g. knip --max-issues 50). This blocks regressions while you burn down the rest.
• Run report-only with --no-exit-code while you're still triaging.

Suppress only what's justified Copy Chapter

When something is genuinely fine as-is, prefer a specific, documented signal
over a blanket ignore, for example:

• tag an export with e.g. @lintignore or @internal
• use ignoreExportsUsedInFile for internal-only exports
• list known exceptions in ignoreDependencies

Resolving reported issues covers the right tool for each case.

Packages Docs Src Content Docs Guides Configuring Project Files (`packages/docs/src/content/docs/guides/configuring-project-files.md`) Copy Section

title: Configuring Project Files Copy Chapter

The entry and project file patterns are the first and most important
options. Getting those right is essential to help you delete more code and make
Knip faster:

• Start with defaults. Only add targeted entry overrides when needed.
• Use project patterns (with negations) to define the scope for Knip.
• Use production mode to exclude tests and other non-production files.
• Use ignore only to suppress issues in specific files; it does not exclude
  files from analysis.

Let's dive in and expand on all of these.

Entry files Copy Chapter

Avoid adding too many files as entry files:

1. Knip does not report unused exports in entry files by default.
2. Proper entry and project patterns allow Knip to find unused files and
   exports.

Unused files Copy Chapter

Files are reported as unused if they are in the set of project files, but are
not resolved from the entry files:

unused files = project files - (entry files + resolved files)

See entry files to see where Knip looks for entry files. Fine-tune entry
and adjust project to fit your codebase.

:::tip

Use negated project patterns to precisely include/exclude files for unused
files detection.

Use ignore* to suppress specific issues in matching files; it does not exclude
files from analysis.

:::

Negated patterns Copy Chapter

When there are too many files in the analysis, start here.

For instance, routes are entry files except those prefixed with an underscore:

{
  "entry": ["src/routes/*.ts", "!src/routes/_*.ts"]
}

Some files are not part of your source and are reported as unused (false
positives)? Use negated project patterns:

{
  "entry": ["src/index.ts"],
  "project": ["src/**/*.ts", "!src/exclude/**"]
}

❌   Don't use ignore for generated artifacts:

{
  "entry": ["src/index.ts", "scripts/*.ts"],
  "ignore": ["build/**", "dist/**", "src/generated.ts"]
}

✅   Do define your project boundaries:

{
  "entry": ["src/index.ts", "scripts/*.ts"],
  "project": ["src/**", "scripts/**"],
  "ignore": ["src/generated.ts"]
}

Why this is better:

• project defines what belongs to the codebase, so build outputs are excluded
  from analysis and unused file detection
• ignore is for the few files that should be analyzed but contain exceptions
• Improves performance by analyzing fewer files

Ignore issues in specific files Copy Chapter

Use ignore when a specific analyzed file is not handled properly by Knip or
intentionally contains unused exports (e.g. generated files exporting
"everything"):

{
  "entry": ["src/index.ts"],
  "project": ["src/**/*.ts"],
  "ignore": ["src/generated.ts"]
}

Also see ignoreExportsUsedInFile for a more targeted approach.

Production Mode Copy Chapter

Default mode includes tests and other non-production files in the analysis. To
focus on production code, use production mode.

Don't try to exclude tests via ignore or negated project patterns. That's
inefficient and ineffective due to entries added by plugins. Use production mode
instead.

❌   Don't do this:

{
  "ignore": ["**/*.test.js"]
}

Why not: ignore hides issues from the report; it does not exclude files from
analysis.

❌   Also don't do this:

{
  "entry": ["index.ts", "!**/*.test.js"]
}

Why not: plugins add test files as entry files; you can't and shouldn't
override that globally.

❌   Or this:

{
  "project": ["**/*.ts", "!**/*.spec.ts"]
}

Why not: project is for unused file detection; negating test files is
ineffective because they are entry files.

✅   Do this instead:

knip --production

To fine-tune the resulting production file set, for instance to exclude test
helper files that still show as unused, use the exclamation mark suffix on
production patterns:

{
  "entry": ["src/index.ts!"],
  "project": ["src/**/*.ts!", "!src/test-helpers/**!"]
}

Remember to keep adding the exclamation mark suffix! for production file
patterns.

:::tip

Use the exclamation mark (!) on both ends (!) to exclude files in production
mode.

:::

Defaults & Plugins Copy Chapter

To reiterate, the default entry and project files for each workspace:

{
  "entry": [
    "{index,cli,main}.{js,cjs,mjs,jsx,ts,cts,mts,tsx}",
    "src/{index,cli,main}.{js,cjs,mjs,jsx,ts,cts,mts,tsx}"
  ],
  "project": ["**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx}!"]
}

Next to this, there are other places where Knip looks for entry files.

Additionally, plugins have plenty of entry files configured that are
automatically added as well.

Packages Docs Src Content Docs Guides Contributing (`packages/docs/src/content/docs/guides/contributing.md`) Copy Section

title: Contributing to Knip Copy Chapter

Here are some ways to contribute to Knip:

• Spread the word!
• Star the project
• File an issue with a reproduction
• Pull requests are welcome

Writing a plugin is a great and fun way to get started.

The CONTRIBUTING.md and DEVELOPMENT.md guides should get you up and
running quickly.

The main goal of Knip is to keep projects clean & tidy. Everything that
contributes to that goal is welcome!

Packages Docs Src Content Docs Guides Handling Issues (`packages/docs/src/content/docs/guides/handling-issues.mdx`) Copy Section

title: Resolve reported issues Copy Chapter

import { Tabs, TabItem } from '@astrojs/starlight/components';

When Knip reports something you didn't expect, it's telling the truth about its
module graph: it couldn't reach that code from an entry file. So a
surprising result is usually a real finding or a configuration gap, not a false
positive to silence. The fix is to teach Knip about your project, issue type by
issue type.

Work the types top-down. Findings come in chains, so reducing unused files also
reduces unused exports and dependencies:

1. Unused files
2. Unresolved imports
3. Unused exports
4. Unused dependencies

Reach for ignore* options only as a last resort, and never before reading
Configuring project files. Hiding a result is not the same as resolving it.

:::tip

Let your coding agent do this for you: the Knip Editor Extension ships an
MCP server that uses these docs to write knip.json for any project.

:::

Unused files Copy Chapter

Getting the list of unused files right trickles down into the other issue types
as well, so we start here. Files are reported as unused if they are in the set
of project files, but not in the set of files resolved from the entry files:

unused files = project files - (entry files + resolved files)

:::tip

Addressing reported Configuration Hints first might help significantly,
especially when handling unused files.

:::

Common causes for unused files include:

• Missing generated files
• Dynamic import specifiers
• Unsupported arguments in scripts
• Unsupported file formats
• Missing plugin
• Incomplete plugin
• Relative paths across workspaces
• Integrated monorepos
• Auto-mocking or auto-imports

In most cases you can add entry patterns manually.

Use --files to filter the report and focus only on unused files:

knip --files

This works with other issue types as well. For instance, use --dependencies to
focus only on dependencies and exclude issues related to unused files and
exports.

:::caution

Don't add unused files to the ignore option before reading configuring
project files. Learn why and when to use entry, project, production mode
and ignore* patterns for better results and performance.

:::

Missing generated files Copy Section

For certain features, Knip needs to run after relevant files are generated. For
instance, source mapping in a monorepo may require files to be built into
dist folders first. And generated files in the src directory may import
other files. For instance, the src/routeTree.gen.ts file generated by
@tanstack/router must exist so Knip can find the imported route files.

Solution: compile and/or generate the relevant files first so Knip can
resolve and find the source files.

If Knip still reports false positives, you may need to strategically add an
entry file manually.

Dynamic import specifiers Copy Section

Dynamic import specifiers aren't resolved, such as:

const entry = await import(path.join(baseDir, 'entry.ts'));

Solution: add entry.ts to entry patterns.

Unsupported arguments in scripts Copy Section

Some tooling command arguments aren't recognized:

{
  "name": "my-lib",
  "version": "1.0.0",
  "scripts": {
    "build": "unknown-build-cli --entry production.ts"
  }
}

Solution: add production.ts to entry patterns.

This works the same for any script, also those in GitHub Actions workflows or
Git hooks. See script parser for more details about Knip's script parser.

Unsupported file formats Copy Section

Entry files referenced in HTML files (e.g. <script src="production.js">).

<html>
  <body>
    <script type="module" src="production.js"></script>
  </body>
</html>

Solution: add production.js to entry patterns. Or add an .html
compiler to extract and resolve the value of <script src> elements.

Knip has support for some popular framework formats through compilers, and
additional compilers can be added for any file type. The recommended solution is
usually to add the file as shown in each example as an entry file.

Missing plugin Copy Section

You might be using a tool or framework for which Knip doesn't have a plugin
(yet). Configuration and entry files (and related dependencies) may be reported
as unused because there is no plugin yet that would include those files. Two
examples:

• Configuration file tool.config.js contains a reference to the package
  "@tool/plugin" → both the file and the dependency are reported as unused.
• A framework automatically imports all files matching src/models/*.ts → those
  files are reported as unused.

Solution: create a new plugin for the tool or framework that's not in
the list yet. Or work around it and add entry patterns and maybe ignore a
dependency or two (using ignoreDependencies).

Incomplete plugin Copy Section

Files may be reported as unused if existing plugins do not include that entry
file pattern yet. See the plugins section of entry files for more details.

Solution: override plugin configuration to customize default patterns
for existing plugins. Or even better: send a pull request to improve the plugin.

Relative paths across workspaces Copy Section

Relative paths to import from other workspaces are not special-cased. For Knip,
it's better to be explicit and list other workspaces as dependencies in
package.json to be used in imports.

Solution: migrate from relative paths...

import { something } from '../../common/file.ts';

...to dependency-based imports...

import { something } from '@org/common';

An additional benefit is that Knip will report unused and unlisted dependencies
from now on.

Integrated monorepos Copy Section

Multiple instances of configuration files like .eslintrc and
jest.config.json across the repository may be reported as unused when working
in a (mono)repo with a single package.json.

Solution: see integrated monorepos for more details and how to
configure plugins to target those configuration files.

Auto-mocking or auto-imports Copy Section

Some frameworks have features like "auto-mocking" or "auto-imports" enabled,
such as Jest and Nuxt.

Solution: include such entry files by extending the entry file patterns.
This is recommended in most cases:

{
  "entry": ["src/index.ts", "src/models/*.ts"]
}

Alternatively, exceptions and outliers can be excluded from the analysis using
negated project patterns:

{
  "project": ["src/**/*.ts", "!**/__mocks__/**"]
}

Unresolved imports Copy Chapter

Knip may ignore or be unable to resolve an import specifier or dependency
references. The most common causes for unresolved imports:

• Template strings
• Extensionless imports
• Unrecognized path aliases
• External aliased imports

Template strings Copy Section

Using template strings in dynamic imports might be ignored or not handled
properly by Knip, resulting in false positives. Examples of dynamic import
template strings:

import(`./${value}.ts`);
import(`@org/name/dist/${value}.js`);

Solution: for internal source files, add the file(s) to the entry
patterns. For external dependencies, add the dependency to the
ignoreDependencies list.

Extensionless imports Copy Section

Knip does not support extensionless imports for some non-standard extensions,
such as for .svg files. Bundlers like Webpack may support this, but Knip does
not. Here's an example:

import Component from './Component';    // → ✅ Should resolve to ./Component.vue
import ArrowIcon from '../icons/Arrow'; // → ❌ Does NOT resolve to ../icons/Arrow.svg

The first import is resolved properly, because .vue is a known extension if a
compiler is registered for that extension (e.g. via the Vue plugin). The second
import might not be resolved, because .svg is not a known extension.

Solution: include the extension. Hosts supporting ES Modules (e.g. Node.js,
browsers) require a file extension for import specifiers.

Unrecognized path aliases Copy Section

Knip resolves config paths, aliases from enabled plugins that read framework
config (e.g. Vite/Webpack resolve.alias, SvelteKit $lib, Nuxt ~/@, Astro,
Docusaurus), and paths configured in knip.json.

Aliases go unrecognized only when no plugin covers the tool, the plugin is
disabled, or the alias lives somewhere Knip doesn't read.

Solution: configure paths or try relative imports. Otherwise, use
ignoreUnresolved as a last resort.

External aliased imports Copy Section

External libraries may use virtual modules not declared in tsconfig.json,
knip.json or readable from a plugin's config.

For instance, unplugin-icons does this to import icons from icon sets as
components. Such imports are reported as unused. Use the paths configuration
option to tell Knip where to find the icon types:

{
  "paths": {
    "~icons/*": ["node_modules/unplugin-icons/types/[framework].d.ts"]
  }
}

Where [framework] is the name of the framework you're using (see available
types).

Solution: configure paths.

Unused exports Copy Chapter

By default, Knip does not report unused exports of entry files.

The most common causes for unused exports include:

• Namespace enumerations
• External libraries
• Custom elements
• CommonJS member access

Use the --exports flag to filter and focus only on issues related to
exports:

knip --exports

Use includeEntryExports to report unused exports of entry files as well.
This can be set per workspace.

Namespace enumerations Copy Section

For exports on an imported namespace, Knip considers all exports referenced if
that namespace is used in certain patterns like enumeration. Individual exports
are then not reported.

Solution: if all exports on imported namespaces should be considered
individually, include the nsExports issue type to disable the heuristic.

See namespace imports to see all related patterns.

External libraries Copy Section

Are the exports consumed or imported by an external library, resulting in a
non-standard consumption of your exports? Here's an example:

export const DynamicApple = dynamic(() =>
  import('./components.js').then(mod => mod.Apple)
);

export const LoadableOrange = loadable(() => import('./components.js'), {
  resolveComponent: components => components.Orange,
});
```

Knip understands Apple is used, since it's standard usage. But Orange is
referenced through a function of an external library. Knip includes external
type definitions to trace such usage, but in some cases it may not be able to
follow the reference through the library's API.

Custom elements Copy Section

A custom element is registered under a tag name rather than imported by its
class name. Knip recognizes the registration and considers the class used. See
Custom Elements for all recognized patterns.

CommonJS member access Copy Section

Named exports consumed via member access on a required variable (const mod = require('./mod'); mod.fn()) are not traced, so they may be reported as unused.
Destructuring (const { fn } = require('./mod')) is traced. See Working with
CommonJS for the conventions that avoid these false positives.

Exclude exports from the report Copy Section

To exclude false positives from the report, there are a few options:

• Ignore exports used in file for exports used internally.

• Individual exports can be tagged using JSDoc syntax.

• Have the export in an entry file:

  • Add the file to the entry file patterns array in the configuration.
  • Move the export(s) to an entry file.
  • Add the file to the exports field of package.json

• Re-export the unused export(s) from an entry file.

Missing unused exports? Copy Section

Did you expect certain exports in the report, but are they missing? They might
be exported from an entry file. In that case, use --include-entry-exports
to make Knip also report unused exports in entry files.

The exports of non-standard extensions like .astro, .mdx, .vue or
.svelte are not available by default. See compilers for more details on
how to include them.

Types used only in signatures of used exports are not reported either.
TypeScript may need them in declaration files, which Knip cannot rule out for
the project or its consumers. Without such output, un-exporting them is safe.

Enum members Copy Section

Unused enums and unused members of exported enums are reported by default.
Reporting such members can be disabled:

knip --exclude enumMembers

Individual enum members can be tagged using JSDoc syntax.

Enums exported from entry files are ignored, and so are their members. Use
--include-entry-exports to make Knip also report members of unused exports
in entry files.

Namespace members Copy Section

Unused members of exported TypeScript namespaces are reported by default.
Reporting such members can be disabled:

knip --exclude namespaceMembers

Individual namespace members can be tagged using JSDoc syntax.

Namespaces exported from entry files are ignored, and so are their members. Use
--include-entry-exports to make Knip also report members of unused exports
in entry files.

Unused dependencies Copy Chapter

Dependencies imported in unused files are reported as unused dependencies.
That's why it's strongly recommended to try and remedy unused files first.
Better entry and project file coverage will solve many cases of reported
unused dependencies.

The most common causes for unused dependencies include:

• Missing or incomplete plugins
• Unrecognized references
• Dependencies named after Node.js builtins
• Conditional or dynamic dependencies
• Type Definition Packages
• Unlisted dependencies
• Unlisted binaries

Use --dependencies to filter the report and focus only on issues related
to dependencies:

knip --dependencies

:::caution[Monorepo]

In a monorepo, a dependency is unused in the root workspace's package.json if
it's also listed in a descendant workspace, and referenced only in the
descendant workspace.

:::

Missing or incomplete plugin Copy Section

If a plugin exists and the dependency is referenced in the configuration file,
but its custom dependency finder does not detect it, then that's a false
positive. Please open a pull request or issue to fix it.

Solution: adding the configuration file as an entry file pattern may be a
temporary stopgap that fixes your situation, but it's better to create a new
plugin or fix an existing one.

Unrecognized reference Copy Section

Sometimes a reference to a dependency is unrecognizable or unreachable to Knip,
so it's a false positive and incorrectly reported as unused.

Solution: add a new plugin or improve an existing one. If you don't feel
like a plugin could solve it, a last resort is to use ignoreDependencies.

If a binary (or "executable") is referenced you'll want to use ignoreBinaries
instead. See unlisted binaries.

Dependencies named after Node.js builtins Copy Section

Some packages have the same name as a Node.js builtin (for instance buffer or
process).

Solution: if Knip reports such a dependency as unused, add it to
ignoreDependencies.

Conditional or dynamic dependencies Copy Section

Dependencies added conditionally in configuration files may not be detected by
Knip. This happens because Knip loads and executes config files, and conditional
logic may evaluate differently during analysis.

For example, this Playwright configuration conditionally adds a reporter:

import { defineConfig } from '@playwright/test';

const reporters: any[] = [['list']];
if (process.env.REPORT_PORTAL_ENABLED) {
  reporters.push(['@reportportal/agent-js-playwright', config]);
}

export default defineConfig({
  reporter: reporters,
});

If process.env.REPORT_PORTAL_ENABLED evaluates to false when Knip runs, the
@reportportal/agent-js-playwright dependency won't be detected and may be
reported as unused.

This limitation exists because Knip executes configuration files to parse their
exported value. While Knip can parse configuration files statically using AST
(Abstract Syntax Tree) analysis, this approach becomes complex very quickly and
most of the time it is easier to use the ignoreDependencies
configuration option for conditionals.

{
  "ignoreDependencies": ["@reportportal/agent-js-playwright"]
}

This pattern can be applied to any plugin that loads configuration files.

Type Definition Packages Copy Section

Bundled types

Many packages come with their type definitions bundled. This means the
package.json#types field in the package points to an internal/local type
definition file. In this case, the separate types package is obsolete.

Knip reporting this is also useful for future regressions: if a package had a
DefinitelyTyped or similar package for its types before and later on starts
shipping those types bundled with the source code, Knip will report the obsolete
types dependency as unused.

Examples include ESLint, Webpack and React Router, rendering the
@types/eslint, @types/webpack and @types/react-router dependencies
obsolete respectively.

Solution: remove the types dependency (often @types/...)

Production types

In strict mode, a dependency used only in type-only source imports can
live in devDependencies. If the dependency is exposed through the package's
built declaration files, it is production usage and must instead be listed in
dependencies or required peerDependencies.

Knip finds this public type graph by following existing declaration files
exposed through main, types, typings, exports, and typesVersions. If
pnpm publishConfig overrides those manifest fields, Knip uses their published
values.

Private workspaces and packages using publishConfig.directory are not
analyzed. Knip only follows existing declaration output and does not guess from
source imports.

Unlisted dependencies Copy Section

This means that a dependency is referenced directly in source code or
configuration, but not listed in package.json.

An unlisted dependency is usually a transitive dependency that's imported or
referenced directly. The dependency is installed (since it's a dependency of
another dependency) and lives in node_modules, but it's not listed explicitly
in package.json.

You should not rely on transitive dependencies for various reasons, including
control, security and stability.

Solution: install and list the dependency in dependencies or
devDependencies.

Unlisted binaries Copy Section

Binaries are executable Node.js scripts. Some npm packages, when installed, add
one or more executable files to be used from scripts in package.json. Examples
include TypeScript that comes with the tsc binary, ESLint comes with eslint,
Next.js with next, and so on.

Knip detects such binaries in scripts and checks whether there's a package
installed that includes that binary. It looks up the bin field in the
package.json file of installed packages. If it doesn't find it, it will be
reported as an unlisted binary as there is no package that contains it.

Binaries that are installed on the OS already and thus likely not meant to be
installed from npm are not reported as unlisted (details: list of ignored
binaries in source).

Missing binaries

An unused dependency and an unlisted binary with the same name indicates
node_modules not containing the relevant package. And this might be caused by
either the way your package manager installs dependencies and binaries, or by
not running Knip from the root of the repository.

Solution: run Knip from the project root. If needed, lint workspaces
individually.

Sometimes binaries and how they're reported can be a bit confusing. See this
example:

{
  "name": "lib",
  "scripts": {
    "commitlint": "commitlint --edit"
  },
  "devDependencies": {
    "@commitlint/cli": "*"
  }
}

This example works fine without anything reported, as the @commitlint/cli
package includes the commitlint binary. However, some script may contain npx commitlint and here Knip assumes commitlint is the name of the package. This
technically works, as commitlint is a transitive dependency of
@commitlint/cli.

Solution: use npx @commitlint/cli

Feedback or false positives? Copy Chapter

If you believe Knip incorrectly reports something as unused (i.e. there's a
false positive), feel free to create a minimal reproduction and open an
issue on GitHub. It'll make Knip better for everyone!

Packages Docs Src Content Docs Guides Issue Reproduction (`packages/docs/src/content/docs/guides/issue-reproduction.md`) Copy Section

title: Issue Reproduction Copy Chapter

If you encounter an issue or false positives when using Knip, you can open an
issue on GitHub. This will help you in your project, and will also improve
Knip for everyone else!

Think of Knip as a kitchen sink, it handles a large amount of projects and
configurations, and your project is different from all others. Many factors may
influence the issue at hand, such as:

• Code syntax, import and export structure in source files
• Dependencies, scripts and entry files in package.json
• TypeScript configuration in tsconfig.json
• Enabled plugins and related configuration files
• Dependent or depending workspaces in a monorepo
• Knip configuration in knip.json

Keep it minimal Copy Chapter

Create the minimum of source code and configuration with a few files to
reproduce and demonstrate the issue. Having this as a basis has many benefits:

• Minimize barriers and unrelated contextual overhead
• Optimize shared understanding of the situation
• Serves as a "contract" to fix the actual issue
• Files serve as a fixture to the project

Providing this with an issue description will help us help you and improve the
chances the issue can be looked into efficiently and in a timely manner.

Useful complements to a minimal reproduction might include:

• Screenshots, videos, code snippets or log output
• Links to an existing project repository
• Applications scaffolded by tools like Angular or Svelte CLI

Before opening an issue Copy Chapter

Before opening an issue, please make sure you:

• are using the latest version
• have read the relevant documentation
• have searched existing issues
• have checked the list of known issues

Please file only a single issue at a time, so each of them can be labeled and
tracked separately.

There is no need to open an issue if you're going to submit a pull request to
close it right away anyway. In that case it's preferred to keep things central
in either an issue or pull request.

Templates Copy Chapter

A convenient way to create a minimal reproduction is by starting with one of
these templates in CodeSandbox or StackBlitz:

Shoutout to CodeSandbox and StackBlitz for generously providing these
free dev containers!

Alternatives Copy Chapter

Other solutions to share a minimal and reproducible case may work well too,
including:

• A public repository on e.g. GitHub or GitLab.
• A pull request with a new test and/or fixture folder.

The goal is to have an easy and common understanding and reproduction. If you're
unable to create a reproduction using one of the methods described then please
clearly explain this in the issue or contact me.

Pull Request Copy Chapter

The optimal way is to add fixtures and failing tests to the Knip repository, and
open a pull request to discuss the issue! Also see instructions for
development.

Packages Docs Src Content Docs Guides Namespace Imports (`packages/docs/src/content/docs/guides/namespace-imports.md`) Copy Section

title: Namespace Imports Copy Chapter

The intention of exports used through namespace imports may not always be clear
to Knip. Here's a guide to better understand how Knip handles such exports.

Example Copy Chapter

We start off by having two exports:

export const version = 'v5';
export const getRocket = () => '🚀';

The next snippet shows how to import all the exports above on a namespace. All
exports of the my-namespace.js module will be members on the NS object:

import * as NS from './my-namespace.js';
import send from 'stats';
send(NS);

The intention of export usage is not always clear. In the example above is
version or getRocket used? We're not sure, but we probably don't want them
to be reported as unused. The same goes for the next example:

import * as NS from './my-namespace.js';

export { NS };

If this is all usage of the NS namespace object, we also don't know whether
individual exports like version or getRocket will be used. However, if at
least one reference to a property such as NS.version is found, then the
individual exports are considered separately again and getRocket will be
marked as unused:

import { NS } from './my-module.js';

const version = NS.version;

The default heuristic Copy Chapter

Knip uses the following heuristic to determine which of the individual exports
are used: