next-unused

A CLI that walks your Next.js dependency graph from the router root and reports the .ts / .tsx files that no one imports.

What you get

Run it and it prints the files nothing points at.

$ npx next-unused
Found 3 unused files:
src/components/OldBanner/index.tsx
src/hooks/useLegacyToggle.ts
src/lib/formatDeprecated.ts

When there is nothing left over, it says No unused files! and exits with 0.

Install

$ npm install --save-dev @piro0919/next-unused

Requires Node 20+.

Use it in CI

--error-on-unused-files exits with code 1 when any are found, so a pull request can fail on leftovers.

{
  "scripts": {
    "find:unused": "next-unused",
    "check:unused": "next-unused --error-on-unused-files"
  }
}

Configuration

Drop a config file in your project root. Picked up in this order: next-unused.config.mjs → .js → .json.

Option	Type	Default	Description
`excludeExtensions`	`string[]`	`[]`	Skip files ending with any of these.
`excludeFiles`	`string[]`	`["middleware.ts"]`	Skip files whose path contains any.
`includeExtensions`	`string[]`	`[".ts", ".tsx"]`	Only consider files with these endings.
`router`	`"app" \| "pages" \| "both"`	`"app"`	Which router to scan as the graph root.
`srcDir`	`boolean`	`true`	Whether your project uses src/.

Programmatic API

The same walk is available as a function.

import { findUnusedFiles, loadConfig } from "@piro0919/next-unused";

const config = await loadConfig();
const unused = await findUnusedFiles({ config });

npm →GitHub →