DEV Community

Tarun Korat
Tarun Korat

Posted on

Introducing Laravel Asset Cleaner: Safely Remove Unused Assets from Your Laravel Projects

#webdev #php #laravel #opensource

Introducing Laravel Asset Cleaner: Safely Remove Unused Assets from Your Laravel Projects

Have you ever inherited a Laravel project and wondered, "Are we actually using all these images?" or "Is this old JavaScript file still needed?" You're not alone.

🤔 The Problem

Over time, Laravel projects accumulate digital clutter:

  • Images from old designs
  • Unused Vue/React components
  • Forgotten CSS files
  • Legacy JavaScript libraries
  • Font files that nobody uses

These unused assets:

  • ✘ Bloat your repository
  • ✘ Slow down deployments
  • ✘ Confuse new developers
  • ✘ Make maintenance harder

But how do you know what's safe to delete? Manual checking is time-consuming and error-prone. Delete the wrong file, and you break production.

💡 The Solution: Laravel Asset Cleaner

I built Laravel Asset Cleaner to solve this exact problem. It's a package that:

  1. Scans your entire Laravel project for assets
  2. Detects which files are actually being used
  3. Reports unused assets with details
  4. Safely removes them with automatic backups

🚀 Quick Start 

# Install
composer require tarunkorat/laravel-asset-cleaner

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

# Scan for unused assets
php artisan assets:scan

# Preview what will be deleted
php artisan assets:delete --dry-run

# Delete with automatic backup
php artisan assets:delete
Enter fullscreen mode Exit fullscreen mode

✨ Key Features

1. Smart Detection

The package scans multiple locations for asset references:

Blade Templates:

<img src="{{ asset('images/logo.png') }}">
<script src="{{ mix('js/app.js') }}"></script>
Enter fullscreen mode Exit fullscreen mode

JavaScript/Vue/React:

import Logo from './images/logo.png';
import Header from './components/Header.vue';
Enter fullscreen mode Exit fullscreen mode

CSS/SCSS:

background-image: url('../images/banner.jpg');
@import 'components/button.css';
Enter fullscreen mode Exit fullscreen mode

PHP Controllers:

$image = Image::make(public_path('images/product.jpg'));
return asset('images/logo.png');
Enter fullscreen mode Exit fullscreen mode

2. Strict Matching (No False Positives!)

A common problem with asset detection is false positives. For example, a file named error.svg might match every occurrence of the word "error" in your code.

Laravel Asset Cleaner uses strict boundary checking to avoid this:

// ❌ Won't match these:
'error' => 'Error message'
throw new Error()

// ✅ Will match these:

import icon from './error.svg'
Enter fullscreen mode Exit fullscreen mode

3. Debug Mode

Not sure why a file is marked as used? Use debug mode:

php artisan assets:debug resources/images/logo.png
Enter fullscreen mode Exit fullscreen mode

Output:

✓ File exists
Path: resources/images/logo.png
Size: 45 KB
🔎 Searching for references...
✓ Found 2 file(s) with references:
• resources/views/layouts/app.blade.php
Match: <img src="{{ asset('images/logo.png') }}">
• resources/js/components/Header.vue
Match: import logo from '@/images/logo.png'
Enter fullscreen mode Exit fullscreen mode

4. Safety Features

  • 💾 Automatic Backups - Creates timestamped backups before deletion
  • 🛡️ Protected Files - Configure files that should never be deleted
  • 👁️ Dry Run Mode - Preview changes without deleting anything
  • ✅ Verification - Confirms files were actually deleted

📊 Real-World Results

I tested this on several production Laravel applications:

Project 1: E-commerce site (3 years old)

  • Found: 156 unused files
  • Freed: 23MB
  • Time saved: ~8 hours of manual checking

Project 2: SaaS application (2 years old)

  • Found: 89 unused files
  • Freed: 12MB
  • Cleaned up: 30 old component files

Project 3: Agency project (5 years old)

  • Found: 203 unused files
  • Freed: 31MB
  • Repository size reduced by 35%

🎯 Common Use Cases

After Refactoring 

# Just removed old components?
php artisan assets:scan --type=js
php artisan assets:delete --type=js
Enter fullscreen mode Exit fullscreen mode

Before Production Deploy 

# Clean everything up
php artisan assets:scan
php artisan assets:delete --force
Enter fullscreen mode Exit fullscreen mode

Optimize Images 

# Find unused images
php artisan assets:scan --type=img
php artisan assets:delete --type=img
Enter fullscreen mode Exit fullscreen mode

CI/CD Integration 

# Generate report in CI pipeline
php artisan assets:scan --json > unused-assets.json
Enter fullscreen mode Exit fullscreen mode

⚙️ Configuration

The package is highly configurable. Here's a snippet from config/asset-cleaner.php:

return [
    // Which asset types to clean
    'clean_types' => ['js', 'css', 'img'],

    // Enable strict matching
    'strict_matching' => true,

    // Define asset locations
    'asset_types' => [
        'js' => [
            'directories' => ['resources/js', 'public/js'],
            'extensions' => ['js', 'jsx', 'ts', 'tsx', 'vue'],
        ],
        'img' => [
            'directories' => ['resources/images', 'public/images'],
            'extensions' => ['jpg', 'png', 'gif', 'svg', 'webp'],
        ],
    ],

    // Files that should never be deleted
    'protected_files' => [
        'resources/js/app.js',
        'resources/css/app.css',
    ],
];
Enter fullscreen mode Exit fullscreen mode

🛠️ How It Works Internally

For the curious developers, here's the high-level architecture:

  1. AssetScanner Service

    • Uses Symfony Finder to locate asset files
    • Stores assets in memory with metadata (size, type, path)

  2. Reference Extraction

    • Scans all PHP, Blade, JS, CSS files
    • Uses regex patterns to find asset references
    • Implements strict boundary matching

  3. Comparison Engine

    • Compares found assets vs referenced assets
    • Marks unused assets for deletion
    • Respects protected files configuration

  4. Safe Deletion

    • Creates timestamped backup directory
    • Copies files before deletion
    • Verifies deletion success
    • Cleans up empty directories

🤝 Contributing

This is my first Laravel package, and I'd love your feedback! The project is open source under the MIT License.

Ways to contribute:

  • 🐛 Report bugs
  • 💡 Suggest features
  • 📖 Improve documentation
  • 🔧 Submit pull requests

GitHub: https://github.com/tarunkorat/laravel-asset-cleaner

📦 Installation & Links 

composer require tarunkorat/laravel-asset-cleaner
Enter fullscreen mode Exit fullscreen mode

🎉 Conclusion

Laravel Asset Cleaner helps you maintain cleaner, more efficient Laravel projects by safely removing unused assets. It's free, open source, and designed with safety as the top priority.

Give it a try and let me know what you think! Have questions or suggestions? Drop them in the comments below. 👇

Star the repo if you find it useful! ⭐

Happy coding! 🚀

Top comments (4)

Collapse
 
xwero profile image
david duymelinck •

I think it is a great idea. The thing I'm wondering is what if they are images that are linked to pages using the database or that are hard linked with the project url in other places. It are edge cases, but cleaning assets can be a job you have to be careful with.
I guess adding a configuration option to have do-not-touch files could solve that problem.

Collapse
 
tarunkorat profile image
Tarun Korat •

We have already built an option for this. You can modify the config file to specify the folders to remove files from, and select which assets you want to clean, like Img, js, and css.

Collapse
 
xwero profile image
david duymelinck •

I didn't see that. Great stuff!

Thread Thread
 
tarunkorat profile image
Tarun Korat •

If you like this one, then don't forget to give a star.