knip で未使用のファイル・依存・export を一掃する

プロジェクトが育つと、使われていないファイル・依存パッケージ・export が静かに溜まっていきます。knip はそれらをまとめて検出してくれるツールです。本記事では導入から設定、CI 連携までを紹介します。

knip とは

JavaScript / TypeScript プロジェクトの「不要なもの」を横断的に見つける静的解析ツールです。ESLint が「1ファイルの書き方」を見るのに対し、knip は プロジェクト全体で誰からも使われていないもの を検出します。

検出できる主なもの:

• 使われていないファイル
• 使われていない依存パッケージ（dependencies / devDependencies）
• package.json に記載が無い依存（unlisted dependencies）
• 使われていない export / 型 export
• 重複した export

インストール

pnpm add -D knip

knip は tsconfig.json やフレームワーク（Next.js など）を自動検出するため、多くのプロジェクトでは設定ゼロでも動きます。

実行する

pnpm knip

未使用のものがあると、種類ごとに一覧で出力されます。

Unused files (2)
  src/lib/old-helper.ts
  src/components/legacy-banner.tsx
 
Unused dependencies (1)
  lodash    package.json
 
Unused exports (1)
  formatLegacyDate  unknown  src/lib/format.ts:42:14

設定する（knip.json）

エントリーポイントと解析範囲を明示したい場合は knip.json を置きます。多くのフレームワークはプラグインで自動認識されますが、明示するとより正確になります。

{
  "entry": ["src/app/**/*.{ts,tsx}", "next.config.ts"],
  "project": ["src/**/*.{ts,tsx}"]
}

• entry … 「ここから辿れれば使用中」とみなす起点
• project … 解析対象のファイル群

よく使うオプション

--fix は便利ですが、削除内容を必ず差分で確認してからコミットしましょう。

CI に組み込む

package.json にスクリプトを足し、CI で実行して未使用を検出したら落とす運用にできます。

{
  "scripts": {
    "knip": "knip"
  }
}

# GitHub Actions の一例
- run: pnpm install --frozen-lockfile
- run: pnpm knip

最初は誤検出（false positive）が出ることもあります。その場合は knip.json の ignore や ignoreDependencies で調整します。

{
  "ignore": ["src/generated/**"],
  "ignoreDependencies": ["some-peer-only-package"]
}

まとめ

knip は「プロジェクトに溜まった不要物」の棚卸しに効きます。導入は数分、最初の実行だけでも驚くほど削れることが多いです。定期的に回す、あるいは CI に組み込んで、コードベースを軽く保ちましょう。