PHPackages                             tarunkorat/laravel-asset-cleaner - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tarunkorat/laravel-asset-cleaner

ActiveLibrary[Utility & Helpers](/categories/utility)

tarunkorat/laravel-asset-cleaner
================================

Safely detect and remove unused CSS, JS, SCSS and other assets from Laravel applications

v1.0.1(6mo ago)745.0k↓35.8%2[1 issues](https://github.com/tarunkorat/laravel-asset-cleaner/issues)1MITPHPPHP ^8.0|^8.1|^8.2|^8.3

Since Nov 12Pushed 6mo agoCompare

[ Source](https://github.com/tarunkorat/laravel-asset-cleaner)[ Packagist](https://packagist.org/packages/tarunkorat/laravel-asset-cleaner)[ Docs](https://github.com/tarunkorat/laravel-asset-cleaner)[ GitHub Sponsors](https://github.com/tarunkorat)[ RSS](/packages/tarunkorat-laravel-asset-cleaner/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (4)Versions (3)Used By (1)

Laravel Asset Cleaner
=====================

[](#laravel-asset-cleaner)

 [![Latest Version](https://camo.githubusercontent.com/463cf8d3c57011112cea8eaea936ec5cd7f2ca8b8a85c96d884d1e3593890468/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746172756e6b6f7261742f6c61726176656c2d61737365742d636c65616e6572)](https://camo.githubusercontent.com/463cf8d3c57011112cea8eaea936ec5cd7f2ca8b8a85c96d884d1e3593890468/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746172756e6b6f7261742f6c61726176656c2d61737365742d636c65616e6572) [![Total Downloads](https://camo.githubusercontent.com/b003cd6217f911dcdc7e3a03a244732aac1b9ba8303788a2c928aa902757236a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f746172756e6b6f7261742f6c61726176656c2d61737365742d636c65616e6572)](https://camo.githubusercontent.com/b003cd6217f911dcdc7e3a03a244732aac1b9ba8303788a2c928aa902757236a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f746172756e6b6f7261742f6c61726176656c2d61737365742d636c65616e6572) [![License](https://camo.githubusercontent.com/f50bb062eaded41a7d1dba1049d96f04152447950b829b566b032b43bca62d65/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f746172756e6b6f7261742f6c61726176656c2d61737365742d636c65616e6572)](https://camo.githubusercontent.com/f50bb062eaded41a7d1dba1049d96f04152447950b829b566b032b43bca62d65/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f746172756e6b6f7261742f6c61726176656c2d61737365742d636c65616e6572) [![Stars](https://camo.githubusercontent.com/c681a78d6bfa87348c09568467f7ba487954bca52961775f1d3ec1f02bab38e6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f746172756e6b6f7261742f6c61726176656c2d61737365742d636c65616e6572)](https://camo.githubusercontent.com/c681a78d6bfa87348c09568467f7ba487954bca52961775f1d3ec1f02bab38e6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f746172756e6b6f7261742f6c61726176656c2d61737365742d636c65616e6572)

Safely detect and remove unused CSS, JS, SCSS, images, and other assets from your Laravel applications. Works seamlessly with Laravel, Laravel Vue, Laravel React, Inertia.js, and Livewire projects.

---

✨ Features
----------

[](#-features)

- 🔍 **Smart Detection** - Scans your entire Laravel project for unused assets
- 🛡️ **Safe Deletion** - Creates backups before removing any files
- 🎯 **Selective Cleaning** - Choose specific asset types (JS, CSS, images, fonts, etc.)
- 📊 **Detailed Reports** - See exactly what will be deleted and why
- 🔎 **Debug Mode** - Investigate why files are marked as used or unused
- ⚡ **Fast Scanning** - Efficiently processes large projects
- 🎨 **Framework Agnostic** - Works with Mix, Vite, plain webpack, and more
- 🔒 **Protected Files** - Never accidentally delete important files
- 📝 **Strict Matching** - Avoids false positives with intelligent pattern matching
- 🌟 Wildcard Support (New in v1.0.1) - Use wildcards in directory patterns

📋 Requirements
--------------

[](#-requirements)

- PHP 8.2 or higher
- Laravel 9.x, 10.x, 11.x, or 12.x
- Composer

🚀 Installation
--------------

[](#-installation)

```
composer require tarunkorat/laravel-asset-cleaner
```

### Publish Configuration

[](#publish-configuration)

```
php artisan vendor:publish --tag=asset-cleaner-config
```

This creates `config/asset-cleaner.php` where you can customize settings.

📖 Usage
-------

[](#-usage)

### Basic Commands

[](#basic-commands)

#### Scan for Unused Assets

[](#scan-for-unused-assets)

```
# Scan all asset types
php artisan assets:scan

# Scan specific types
php artisan assets:scan --type=js --type=css
php artisan assets:scan --type=img

# Show detailed information
php artisan assets:scan --details

# Output as JSON
php artisan assets:scan --json
```

#### Delete Unused Assets

[](#delete-unused-assets)

```
# Dry run (preview what will be deleted)
php artisan assets:delete --dry-run

# Delete with confirmation
php artisan assets:delete

# Delete without confirmation
php artisan assets:delete --force

# Delete without backup
php artisan assets:delete --no-backup --force

# Delete specific types
php artisan assets:delete --type=js --type=css
```

#### Debug Mode

[](#debug-mode)

```
# Debug specific file
php artisan assets:debug resources/images/logo.png

# Show all found assets
php artisan assets:debug --show-all

# Show all reference patterns
php artisan assets:debug --show-refs

# Debug specific type
php artisan assets:debug --type=js --show-all
```

### Example Workflow

[](#example-workflow)

```
# Step 1: Scan for unused assets
php artisan assets:scan

# Output:
# Found 15 unused asset(s):
#   📦 js (5 files)
#      📄 resources/js/old-component.js (2.5 KB)
#      📄 public/js/legacy-script.js (8.2 KB)
#   📦 css (4 files)
#      📄 resources/css/unused-styles.css (3.1 KB)
#   📦 img (6 files)
#      📄 public/images/old-logo.png (45 KB)

# Step 2: Preview deletion
php artisan assets:delete --dry-run

# Step 3: Delete unused assets
php artisan assets:delete

# Step 4: Verify backup created
# Backup location: storage/asset-cleaner-backup/2024-11-12_153045/
```

⚙️ Configuration
----------------

[](#️-configuration)

Edit `config/asset-cleaner.php`:

```
return [
    // Specify which asset types to clean by default
    'clean_types' => 'all', // or ['js', 'css', 'img']

    // Enable strict matching (recommended)
    'strict_matching' => true,

    // Define asset types and their locations
    'asset_types' => [
        'js' => [
            'directories' => [
                'resources/js',
                'public/js',
                'public/js/*',  // ✨ NEW: Wildcard support
            ],
            'extensions' => ['js', 'jsx', 'ts', 'tsx', 'vue', 'mjs'],
        ],
        'css' => [
            'directories' => [
                'resources/css',
                'resources/sass',
                'public/css',
                'public/css/*',  // ✨ NEW: Scans css/vendor, css/admin, etc.'
            ],
            'extensions' => ['css', 'scss', 'sass', 'less'],
        ],
        'img' => [
            'directories' => [
                'resources/images',
                'public/images',
                'public/assets/**',  // ✨ NEW: Recursive wildcard
            ],
            'extensions' => ['jpg', 'jpeg', 'png', 'gif', 'svg', 'webp', 'ico'],
        ],
        // ... more types
    ],

    // Directories to scan for asset references
    'scan_directories' => ['app', 'resources/views', 'resources/js', 'routes'],

    // Files that should never be deleted
    'protected_files' => [
        'resources/js/app.js',
        'resources/css/app.css',
    ],

    // Backup settings
    'backup_directory' => storage_path('asset-cleaner-backup'),
    'create_backup' => true,
];
```

🔍 How It Works
--------------

[](#-how-it-works)

### Detection Process

[](#detection-process)

1. **Scans Asset Directories** - Finds all assets in configured directories
2. **Searches for References** - Looks for asset usage in:
    - Blade templates (`asset()`, ``, ``, ``)
    - JavaScript files (imports, requires, dynamic imports)
    - CSS files (`url()`, `@import`, background images)
    - PHP controllers (`Image::make()`, `public_path()`, `Storage::url()`)
    - Vue/React components (import statements, src attributes)
    - Build configs (webpack.mix.js, vite.config.js, package.json)
3. **Strict Matching** - Only matches complete filenames with extensions
4. **Safe Deletion** - Creates timestamped backups before removal

### Wildcard Directory Patterns (New in v1.0.1)

[](#wildcard-directory-patterns-new-in-v101)

You can now use wildcard patterns in your directory configuration for more flexible asset scanning.

**Single Level Wildcard (\*)**Single Level Wildcard (\*)

```
'directories' => [
    'public/css/*',  // Scans: public/css/vendor, public/css/admin, public/css/themes
]

```

**Example structure:**

```
public/css/
  ├── app.css           ✅ Scanned
  ├── vendor/
  │   └── bootstrap.css ✅ Scanned
  └── admin/
      └── style.css     ✅ Scanned

```

\*\*Recursive Wildcard **(**) Scans the directory and ALL subdirectories recursively:

```
'directories' => [
    'public/assets/**',  // Scans everything under public/assets
]

```

**Example structure:**

```
public/assets/
  ├── css/
  │   ├── app.css              ✅ Scanned
  │   └── vendor/
  │       └── bootstrap.css    ✅ Scanned
  ├── js/
  │   └── app.js               ✅ Scanned
  └── images/
      └── logo.png             ✅ Scanned

```

### What Gets Detected

[](#what-gets-detected)

✅ **These patterns are detected:**

```
// Blade templates

// JavaScript
import Logo from './images/logo.png';
require('./components/Header.vue');

// CSS
background-image: url('../images/banner.jpg');
@import 'components/button.css';

// PHP Controllers
$image = Image::make(public_path('images/product.jpg'));
return asset('images/logo.png');
```

❌ **False positives avoided:**

- File named `error.svg` won't match word "error" in code
- `test.js` won't match variable named "test"
- Strict boundary checking prevents partial matches

🛡️ Safety Features
------------------

[](#️-safety-features)

- ✅ **Automatic Backups** - All deleted files are backed up with timestamps
- ✅ **Protected Files** - Important files (app.js, app.css) are never deleted
- ✅ **Dry Run Mode** - Preview changes before applying them
- ✅ **Confirmation Prompts** - Asks for confirmation before deletion
- ✅ **Verification** - Checks if files were actually deleted
- ✅ **Error Logging** - Failed deletions are logged for review

🎯 Use Cases
-----------

[](#-use-cases)

### Clean Up After Refactoring

[](#clean-up-after-refactoring)

```
# After removing old components
php artisan assets:scan --type=js
php artisan assets:delete --type=js --dry-run
```

### Optimize Images

[](#optimize-images)

```
# Find unused images
php artisan assets:scan --type=img
php artisan assets:delete --type=img
```

### CI/CD Integration

[](#cicd-integration)

```
# In your deployment script
php artisan assets:scan --json > unused-assets-report.json
```

### Before Production Deploy

[](#before-production-deploy)

```
# Clean up everything
php artisan assets:scan
php artisan assets:delete --force
```

🐛 Troubleshooting
-----------------

[](#-troubleshooting)

### Files Not Being Detected as Unused

[](#files-not-being-detected-as-unused)

```
# Debug specific file
php artisan assets:debug resources/js/MyComponent.vue

# This will show:
# - Where the file is located
# - What references it (if any)
# - Why it's marked as used/unused
```

### Files Won't Delete

[](#files-wont-delete)

Common causes:

- File permissions (run as administrator on Windows)
- File is open in an editor
- Antivirus blocking deletion

Solution:

```
# Check what failed
# Check Laravel logs: storage/logs/laravel.log

# Try with elevated permissions (Windows)
# Run PowerShell as Administrator
php artisan assets:delete --force
```

### False Positives

[](#false-positives)

If files are incorrectly marked as used:

```
// config/asset-cleaner.php
'strict_matching' => true, // Ensure this is enabled
```

### Restore from Backup

[](#restore-from-backup)

```
# Backups are in storage/asset-cleaner-backup/
# Each run creates a timestamped folder

# To restore:
cp -r storage/asset-cleaner-backup/2024-11-12_153045/* ./
```

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

### Development Setup

[](#development-setup)

```
# Clone the repository
git clone https://github.com/tarunkorat/laravel-asset-cleaner.git

# Install dependencies
composer install
```

📝 Changelog
-----------

[](#-changelog)

Please see [CHANGELOG.md](CHANGELOG.md) for recent changes.

🔒 Security
----------

[](#-security)

If you discover any security issues, please email  instead of using the issue tracker.

📄 License
---------

[](#-license)

The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.

💖 Support
---------

[](#-support)

If this package helped you, please consider:

- ⭐ Starring the repository
- 🐛 Reporting bugs
- 💡 Suggesting new features
- 📖 Improving documentation

🙏 Credits
---------

[](#-credits)

- [Tarun Korat](https://github.com/tarunkorat)

🔗 Links
-------

[](#-links)

- [Documentation](https://github.com/tarunkorat/laravel-asset-cleaner#readme)
- [Packagist](https://packagist.org/packages/tarunkorat/laravel-asset-cleaner)
- [GitHub](https://github.com/tarunkorat/laravel-asset-cleaner)
- [Issues](https://github.com/tarunkorat/laravel-asset-cleaner/issues)

---

Made with ❤️ by [Tarun Korat](https://github.com/tarunkorat)

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance65

Regular maintenance activity

Popularity37

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

2

Last Release

207d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/44538ddc1b10186c30a1c6f8d2c9b3201f3b26bf601fff1b4d17d7e755aa7a43?d=identicon)[tarunkorat](/maintainers/tarunkorat)

---

Top Contributors

[![tarunkorat](https://avatars.githubusercontent.com/u/108346132?v=4)](https://github.com/tarunkorat "tarunkorat (5 commits)")

---

Tags

assetsassets-managementcleanuplaravellaravel-packageoptimizationphpreactvuelaravelcssJSimagesoptimizationassetsreactvuecleanercleanupunused

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/tarunkorat-laravel-asset-cleaner/health.svg)

```
[![Health](https://phpackages.com/badges/tarunkorat-laravel-asset-cleaner/health.svg)](https://phpackages.com/packages/tarunkorat-laravel-asset-cleaner)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[illuminate/session

The Illuminate Session package.

9938.5M818](/packages/illuminate-session)[stolz/assets

An ultra-simple-to-use assets management library

289527.4k8](/packages/stolz-assets)[fisharebest/laravel-assets

Asset management for Laravel

208.1k](/packages/fisharebest-laravel-assets)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)