Dead Code Finder

A CLI tool to help developers identify and remove unused components, functions, variables, and files in their React and Next.js projects. This helps in reducing bundle size, improving performance, and maintaining a cleaner codebase.

Features

• Comprehensive Scan: Detects unused:
  • React Components
  • JavaScript/TypeScript Functions
  • Variables
  • Files
  • Imports
• React & Next.js Aware: Specifically designed to understand common patterns in React and Next.js applications, including App Router and Page Router conventions.
• TypeScript Support: Fully compatible with TypeScript projects (.ts, .tsx files).
• Configurable: Customize source directories and ignore patterns via CLI or configuration file.
• Detailed Report: Provides a summary of findings and a list of identified dead code with line numbers, including potential file size savings.

Installation

You can install the package globally using npm or yarn:

npm install -g dead-code-finder
# OR
yarn global add dead-code-finder

Usage

Once installed, you can run the find-dead-code command in your project's root directory.

find-dead-code scan

Options

You can customize the scan behavior using the following options:

• -s, --src <directory>: Specify the source directory to scan (overrides config file).
  • Example: find-dead-code scan --src ./app
• -i, --ignore <patterns...>: Provide a list of glob patterns to ignore (overrides config file).
  • Example: find-dead-code scan --ignore "**/lib/**" "**/utils/**"
• -c, --config <path>: Path to configuration file (default: deadcoderc.json).
  • Example: find-dead-code scan --config ./custom-config.json

Full Example:

find-dead-code scan --src ./src --ignore "**/api/**" "**/types/**"

Configuration File

For larger projects or more complex setups, you can use a configuration file instead of CLI arguments. The tool will automatically look for deadcoderc.json in your project root.

Create a sample configuration:

find-dead-code init

Example configuration file (deadcoderc.json):

{
  "srcDir": "src",
  "ignorePatterns": [
    "**/node_modules/**",
    "**/.next/**",
    "**/dist/**",
    "**/build/**",
    "**/*.test.*",
    "**/*.spec.*",
    "**/__tests__/**",
    "**/__mocks__/**",
    "**/lib/**",
    "**/utils/**"
  ]
}

Configuration precedence:

1. CLI arguments (highest priority)
2. Configuration file
3. Default values (lowest priority)

How it Works (Simplified)

The tool performs a two-pass analysis:

1. Build Usage Map: It first scans all specified source files to identify every unique identifier (component name, function name, variable name) and records where each one is used throughout the codebase. It intelligently skips common built-in JavaScript/React/Next.js identifiers and basic patterns.
2. Analyze Definitions: In the second pass, it identifies all definitions (components, functions, variables, imports) within each file. For each definition, it checks against the previously built usage map.
   • If an identifier is defined but has no recorded usages outside its own defining file, it's flagged as potentially unused.
   • Special heuristics are applied for React components (e.g., PascalCase naming, presence of JSX, hooks) and Next.js entry points (e.g., page.tsx, layout.tsx) to prevent false positives.
   • Files are marked as unused if they are not imported anywhere and are not identified as Next.js entry points.

Limitations & Future Improvements

• Regex-based Analysis: The current implementation relies on regular expressions. While effective for many cases, regex cannot fully understand the complex syntax tree of JavaScript/TypeScript. This means there might be:
  • False Positives: Code that appears unused to regex but is dynamically called or used in ways not captured by patterns.
  • False Negatives: Code that is truly dead but is missed by the current patterns.
  • Contextual Understanding: It struggles with advanced scenarios like HOCs, render props, or complex dependency injection without deeper AST analysis.
• AST-based Analysis: For a more robust and accurate dead code detection, a future improvement would involve migrating to an Abstract Syntax Tree (AST) parser (e.g., using @babel/parser or TypeScript's own compiler API). This would allow for a precise understanding of code structure and dependencies.
• Unused Exports: Accurately identifying truly unused exports (i.e., code exported from a module but never imported by another module) requires building a full dependency graph of the entire project, which is significantly more complex than the current scope. The current tool focuses more on definitions that are not used anywhere.
• Configuration File: Allow configuration via a deadcoderc.json or package.json entry.
• ESLint Integration: Provide ESLint rules that leverage this analysis.

Contributing

Contributions are welcome! If you find a bug, have a feature request, or want to contribute code, please open an issue or submit a pull request on the GitHub repository.

License

This project is licensed under the MIT License.