✂️ CodePrune

A fast, reliable CLI tool to detect and safely clean up unused files and imports in your JS/TS projects (React, Next.js, React Native, Node.js).

CodePrune parses your imports and builds a complete dependency graph starting from your entry points, flagging any source file that is completely unreachable.

🚀 Installation

Install globally via npm:

npm install -g codeprune

⚡ Quick Start

Use the init command to generate a config file. It auto-detects your framework from package.json:

codeprune init              # Auto-detect with interactive selection
codeprune init --yes       # Auto-detect and create config automatically
codeprune init react       # Use specific framework

This creates a codeprune.config.json with sensible defaults for your project.

Supported frameworks: Next.js, React, React Native, Vue, Svelte, Express, Node.js

---

🔍 How to Scan Your Project

Once installed globally, you can use codeprune in any local JS/TS project.

1. Create a Configuration File

In the root directory of the project you want to scan, create a codeprune.config.json file. This tells CodePrune where to look and where your dependency graph starts.

For Next.js:

{
  "exclude": ["node_modules", ".next", "out", "public"],
  "extensions": [".js", ".ts", ".tsx", ".jsx"],
  "entry": ["app", "pages", "src"]
}

For React (Vite/Create React App):

{
  "exclude": ["node_modules", "dist", "build"],
  "extensions": [".js", ".ts", ".tsx", ".jsx"],
  "entry": ["src/main.tsx", "src/index.tsx"]
}

For React Native:

{
  "exclude": ["node_modules", "android", "ios", ".expo"],
  "extensions": [".js", ".ts", ".tsx", ".jsx"],
  "entry": ["App.tsx", "index.js"]
}

2. Run the Scanner

Run the following command in your terminal:

codeprune

You can also output the results in JSON format (ideal for CI/CD pipelines):

codeprune --json

---

🛠️ How to Fix (Clean Up) Unused Files

Once you have run the scanner, CodePrune will output a list of unused files.

Step 1: Review the Output

The CLI groups files into two categories:

• ❌ Unused Files: Files that are definitely not imported anywhere in the graph.
• ⚠️ Possibly Unused: Files that are only referenced via dynamic imports (e.g., import('./MyComponent')). Static analysis cannot confidently guarantee these are unused, so verify manually!

Step 2: Delete Unused Files using the --delete flag

CodePrune features a built-in safe delete mode. Rather than permanently deleting your files immediately, it moves them to a local trash folder.

Run the scan with the delete flag:

codeprune --delete

This will automatically:

1. Scan your project.
2. Identify the ❌ Unused Files.
3. Move all unused files out of your workspace and into a .codeprune-trash folder in your project's root.

Interactive Mode (Keyboard Navigation)

For more control over which files to delete, use the interactive mode:

codeprune --delete --interactive

This opens an interactive file selector where you can:

Key	Action
↑ / ↓	Navigate through files
Space	Toggle file selection
Tab	Select/deselect all files
Enter	Delete selected files
Escape	Cancel and exit

Files are moved to .codeprune-trash for safe recovery.

What to check after running:

1. Run your build/dev server (npm run dev) to ensure nothing broke.
2. If a file was accidentally flagged as unused and your app broke, restore it using codeprune restore --all or codeprune restore --file "path/to/file"
3. Once you verify your project builds fine, you can permanently delete the .codeprune-trash folder.

Restore Deleted Files

Use the restore command to recover files from .codeprune-trash:

codeprune restore              # List files in trash
codeprune restore --all       # Restore all files
codeprune restore --file src/components/Button.tsx  # Restore specific file

---

🔧 Fix Unused Code

CodePrune can also clean up unused imports, variables, functions, classes, and more:

codeprune --fix-imports

This will:

1. Remove unused imports - Identifies imports that are never used in the file and removes them
2. Remove unused declarations - Removes unused variables, functions, classes, interfaces, and type aliases
3. Organize imports - Groups and sorts imports (external modules first, then relative imports, alphabetically sorted)

You can combine with other options:

codeprune --fix-imports --delete

---

⚙️ Configuration Reference

Option	Type	Description
include	string[]	Directories to recursively scan for source files.
exclude	string[]	Directories to completely ignore (e.g., node_modules).
extensions	string[]	File extensions to track (.js, .tsx, .ts, etc.).
entry	string[]	The starting points of your app. Can be specific files (src/index.js) or directories (src/pages).
ignore	string[]	Specific folders/patterns to skip within included directories.

---

⌨️ CLI Commands

Help

codeprune help    # Show available commands and options

Init

codeprune init                  # Auto-detect framework (interactive)
codeprune init --yes            # Auto-detect and create config automatically
codeprune init react            # Use specific framework
codeprune init -o custom.json   # Custom output path

The init command auto-detects your framework from:

• package.json dependencies (next, react, vue, svelte, express, etc.)
• Config files (next.config.js, vite.config.ts, svelte.config.js)

Supported frameworks: next, react, react-native, node, vue, svelte, express

Restore

codeprune restore              # List files in trash
codeprune restore --all        # Restore all files
codeprune restore -f <file>    # Restore specific file

Options

Option	Alias	Description
--config	-c	Custom config file path
--json	-j	Output results in JSON format
--delete	-d	Move unused files to .codeprune-trash
--interactive	-i	Interactive file selection (use with --delete)
--fix-imports	-f	Remove unused imports and organize imports