Unused File Cleaner

A command-line tool to identify and manage unused JavaScript/TypeScript files in your project's src directory. This tool helps keep your codebase clean by detecting files that are not imported or used anywhere in your project.

Features

• Scans for unused JavaScript, TypeScript, JSX, and TSX files
• Preserves specified entry point file
• Maintains original directory structure when moving files
• Supports custom exclude paths
• Detects various import patterns:
  • ES6 imports
  • Dynamic imports
  • CommonJS require
  • Side effect imports
  • CSS/SCSS imports
  • Destructured imports
  • Class extends

Installation

npm install unused-file-cleaner

Or globally:

npm install -g unused-file-cleaner

Usage

Command Line Interface

Basic usage:

npx unused-file-cleaner

With options:

npx unused-file-cleaner \
  --root ./my-project \
  --output unused-files \
  --exclude node_modules,dist,tests \
  --entry-point src/main.jsx

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --root | -r | Project root directory | Current working directory | | --output | -o | Output directory for unused files | unused-js-files | | --exclude | -e | Comma-separated paths to exclude | node_modules,dist,.git,build | | --entry-point | -p | Entry point file (relative to src) | src/main.jsx | | --version | -v | Show version number | - | | --help | -h | Show help | - |

Programmatic Usage

You can also use the tool programmatically in your Node.js scripts:

const JSUnusedFileCleaner = require('unused-file-cleaner');

const cleaner = new JSUnusedFileCleaner({
    projectRoot: './my-project',  // change this path to your project root path
    outputDir: 'unused-files',  // define output folder name 
    excludePaths: ['node_modules', 'dist', 'tests'],  // define exclude path
    entryPoint: 'src/main.jsx'  // define entry point of the project
});

cleaner.moveUnusedFiles()
  .then(result => {
    console.log('----------------------------------------');
    console.log('📊 Results Summary:');
    console.log('----------------------------------------');
    console.log(`Total files scanned: ${result.total}`);
    console.log(`Unused files found: ${result.unused}`);
    console.log('\n📁 Moved files:');
    result.files.forEach(file => console.log(`- ${file}`));
    console.log('\n✅ Files have been moved to: unused-js-files/');
  })
  .catch(err => {
    console.error('❌ Error:', err);
    process.exit(1);
  });

Configuration

The tool accepts the following configuration options:

{
    projectRoot: string,    // Root directory of your project
    outputDir: string,      // Directory where unused files will be moved
    excludePaths: string[], // Paths to exclude from scanning
    entryPoint: string     // Entry point file that should never be removed
}

How It Works

1. Scans the src directory for all JavaScript/TypeScript files
2. Analyzes import statements and references in each file
3. Preserves the specified entry point file
4. Identifies files that are not imported or used anywhere
5. Moves unused files to the specified output directory
6. Maintains the original directory structure in the output

Supported Import Patterns

The tool detects the following import patterns:

// ES6 imports
import { Component } from './component';
import DefaultExport from './module';

// Dynamic imports
import('./module');

// CommonJS require
const module = require('./module');

// Side effect imports
import './styles.css';

// Destructured imports
export { something } from './module';

// Class extends
class MyComponent extends BaseComponent

Notes

• The tool only scans files within the src directory
• Files are moved, not deleted, so you can review them before removing
• The entry point file is always preserved
• Original directory structure is maintained in the output directory

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Author

Jignesh Goyal

Support

If you encounter any issues or have questions, please create an issue on the GitHub repository.