TypeScript Unused Cleaner

A blazingly fast tool to detect unused TypeScript/JavaScript code including React components, types, interfaces, functions, variables, and enums in your codebase.

Features

• 🚀 Lightning Fast - Written in Rust with parallel processing
• 🎯 Comprehensive Detection - Components, types, interfaces, functions, variables, enums
• ⚙️ Configurable - Flexible configuration with JSON files
• 📊 Detailed Reports - Clear output with usage statistics
• 🔧 CI/CD Ready - Exit codes and thresholds for automation
• 📁 Monorepo Support - Handles complex project structures
• ⚛️ React Optimized - Special patterns for React components and hooks

Installation

From NPM (Recommended)

npm install -g ts-unused-cleaner
# or
npx ts-unused-cleaner

From Cargo

cargo install ts-unused-cleaner

From Source

git clone https://github.com/your-username/ts-unused-cleaner
cd ts-unused-cleaner
cargo build --release
# Binary will be available at ./target/release/ts-unused-cleaner

Quick Start

# Detect unused React components (default)
ts-unused-cleaner

# Detect all element types
ts-unused-cleaner --all

# Use verbose output
ts-unused-cleaner --all --verbose

# Strict mode (exit with error if unused found)
ts-unused-cleaner --all --strict

Usage

Basic Commands

# Basic scan (components only)
ts-unused-cleaner

# Scan specific element types
ts-unused-cleaner --types --interfaces --functions

# Scan everything
ts-unused-cleaner --all

# Verbose output with performance info
ts-unused-cleaner --verbose

# Quiet mode (errors only)
ts-unused-cleaner --quiet

# Custom number of parallel jobs
ts-unused-cleaner --jobs 8

# Use custom config file
ts-unused-cleaner --config path/to/tuc.config.json

# Strict mode for CI/CD
ts-unused-cleaner --strict

Detection Types

| Flag | Description | Example | |------|-------------|---------| | (default) | React components | function MyComponent(), const Button = () => | | --types | TypeScript type definitions | type User = {...} | | --interfaces | TypeScript interfaces | interface ApiResponse {...} | | --functions | Function declarations | function helper(), const utils = () => | | --variables | Variable/constant declarations | const API_URL = "...", let config = {...} | | --enums | TypeScript enums | enum Status {...} | | --all | All of the above | |

Configuration

Create a tuc.config.json file in your project root:

{
  "search_dirs": ["src", "components", "lib"],
  "exclude_patterns": [
    "node_modules",
    "*.test.ts",
    "*.test.tsx",
    "*.spec.ts",
    "*.spec.tsx",
    "*.stories.ts",
    "*.stories.tsx",
    "*.d.ts",
    "dist",
    "build",
    ".next",
    "coverage",
    "__tests__",
    "tests"
  ],
  "detection_types": {
    "components": true,
    "types": true,
    "interfaces": true,
    "functions": true,
    "variables": true,
    "enums": true
  },
  "ci": {
    "max_unused_elements": 10,
    "fail_on_exceed": true,
    "log_level": "warn"
  }
}

Configuration Files

TS Unused Cleaner looks for configuration files in this order:

1. Custom config file specified via --config flag
2. tuc.config.json in the current directory

If no configuration file is found, the tool will use default settings.

Use Cases

React/Next.js Projects

• Unused React components and hooks
• Dead TypeScript types and interfaces
• Orphaned utility functions
• Unused constants and enums

TypeScript Libraries

• Unused exported types
• Dead utility functions
• Orphaned interfaces
• Unused enum values

Node.js Applications

• Unused helper functions
• Dead configuration objects
• Orphaned type definitions
• Unused middleware

Monorepos

• Cross-package unused exports
• Dead shared utilities
• Unused design system components
• Orphaned type definitions

CI/CD Integration

GitHub Actions

name: Check Unused Code
on: [push, pull_request]

jobs:
  unused-check:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Install TS Unused Cleaner
      run: npm install -g ts-unused-cleaner
    - name: Check for unused code
      run: ts-unused-cleaner --all --strict

Exit Codes

• 0 - Success (no unused elements or within threshold)
• 1 - Error (unused elements found in strict mode or above threshold)

Example Output

🔍 TS Unused Cleaner - Scanning for unused elements...

📊 Detection Results:
┌─────────────┬───────┬──────┬────────┐
│ Type        │ Total │ Used │ Unused │
├─────────────┼───────┼──────┼────────┤
│ Components  │    15 │   12 │      3 │
│ Types       │     8 │    6 │      2 │
│ Interfaces  │     5 │    4 │      1 │
│ Functions   │    20 │   18 │      2 │
│ Variables   │    10 │    8 │      2 │
│ Enums       │     3 │    2 │      1 │
└─────────────┴───────┴──────┴────────┘

❌ Unused Elements Found:

React Components:
  • UnusedModal (src/components/UnusedModal.tsx)
  • OldButton (src/components/OldButton.tsx)
  • DeprecatedCard (src/components/DeprecatedCard.tsx)

Types:
  • UnusedDataType (src/types/api.ts:15)
  • LegacyUser (src/types/user.ts:8)

Functions:
  • unusedHelper (src/utils/helpers.ts:42)
  • deprecatedFormatter (src/utils/format.ts:18)

⏱️  Execution time: 0.12s
🚀 Accelerated by Rust implementation

Performance

TS Unused Cleaner is designed for speed:

• Parallel Processing - Utilizes all CPU cores via Rayon
• Optimized Regex - Compiled patterns with efficient matching
• Memory Efficient - Streaming file processing
• Rust Performance - Native speed with zero-cost abstractions
• Thread Pool Configuration - Configurable via --jobs flag

Typical performance on large codebases:

• 1000+ files: ~0.5-2 seconds
• 10,000+ files: ~5-15 seconds
• Monorepos with 50k+ files: ~30-60 seconds

Performance can be tuned using:

# Use 8 parallel jobs
ts-unused-cleaner --jobs 8

# Maximum parallelism (uses all CPU cores)
ts-unused-cleaner --jobs $(nproc)

Supported Patterns

React Components

• export default function ComponentName
• export const ComponentName = () =>
• export const ComponentName = React.memo()
• export const ComponentName = forwardRef()
• const ComponentName = React.forwardRef()

TypeScript Types

• export type TypeName = ...
• type TypeName = ...

Interfaces

• export interface InterfaceName
• interface InterfaceName

Functions

• export function functionName
• export const functionName = () =>
• function functionName
• const functionName = async () =>

Variables

• export const CONSTANT_NAME
• export let variableName
• const CONSTANT_NAME

Enums

• export enum EnumName
• enum EnumName

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development

# Clone the repository
git clone https://github.com/your-username/ts-unused-cleaner
cd ts-unused-cleaner

# Build the project
cargo build
# or via npm
npm run build

# Run tests
cargo test
# or via npm
npm test

# Format code
cargo fmt
# or via npm
npm run fmt

# Run example
cd example
./demo.sh

Development Dependencies

The project uses several Rust crates for development:

• clap - Command line argument parsing
• serde - Serialization/deserialization
• regex - Pattern matching
• rayon - Parallel processing
• walkdir - File system traversal
• colored - Terminal output coloring
• indicatif - Progress bars

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Rust for maximum performance
• Uses Rayon for parallel processing
• Optimized for TypeScript/JavaScript ecosystems including React, Next.js, Node.js, and more