Asset Cleaner Package for Laravel

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

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

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

Installation

composer require tarunkorat/laravel-asset-cleaner

Publish Configuration

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

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

Usage

Basic Commands

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

# 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 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

# 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

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

Detection Process

Scans Asset Directories - Finds all assets in configured directories
Searches for References - Looks for asset usage in:
- Blade templates (asset(), <img src>, <script>, <link>)
- 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)
Strict Matching - Only matches complete filenames with extensions
Safe Deletion - Creates timestamped backups before removal

Wildcard Directory Patterns (New in v1.0.1)

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

These patterns are detected:

// Blade templates
<img src="{{ asset('images/logo.png') }}">
<script src="{{ mix('js/app.js') }}"></script>

// 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

✅ 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

Clean Up After Refactoring

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

Optimize Images

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

CI/CD Integration

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

Before Production Deploy

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

Troubleshooting

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

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

If files are incorrectly marked as used:

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

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/* ./

You can learn more about this package, get full installation instructions, and view the source code on GitHub.