## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require mrclay/minify:^4.0

Publish the config file (if needed):

php artisan vendor:publish --provider="Mrclay\Minify\MinifyServiceProvider"

Basic Usage Add the package to your app/Providers/AppServiceProvider.php:

use Mrclay\Minify\Facades\Minify;

public function boot()
{
    Minify::addResource('css', [
        'path/to/main.css',
        'path/to/extra.css'
    ]);
}

First Use Case Generate a minified URL in your Blade template:
```
<link href="{{ Minify::url('css') }}" rel="stylesheet">
```
SCSS Support The package now supports SCSS preprocessing via scssphp 2.x while maintaining backward compatibility with older CSS files. No additional configuration is required—simply include .scss files as you would .css files:
```
Minify::addResource('scss-bundle', [
    'resources/scss/main.scss',
    'resources/scss/theme.scss'
]);
```

Implementation Patterns

Common Workflows

1. Dynamic Resource Management (Updated for SCSS)

Add SCSS Resources

Minify::addResource('admin-scss', [
    'resources/scss/admin/dashboard.scss',
    'resources/scss/admin/components/*.scss'
]);

Mixed CSS/SCSS Bundles

Minify::addResource('app-assets', [
    'public/css/vendor.css',          // Plain CSS
    'resources/scss/app.scss',        // SCSS
    'public/css/legacy/old.css'       // Legacy CSS
]);

2. Integration with Laravel Mix/Vite (SCSS Focus)

SCSS Processing in Mix Configure webpack.mix.js to compile SCSS:

mix.sass('resources/scss/app.scss', 'public/css')
  .then(() => {
      console.log('SCSS compiled to:', mix.config.output.css.paths);
  });

Then feed the output to mrclay/minify:

Minify::addResource('app-css', [
    'public/css/app.css' // Compiled from SCSS
]);

Vite + SCSS Ensure Vite processes SCSS in vite.config.js:

export default {
    css: {
        preprocessorOptions: {
            scss: {
                additionalData: '@import "variables";'
            }
        }
    }
};

Use the generated CSS in mrclay/minify:

$manifest = json_decode(file_get_contents(public_path('build/assets/manifest.json')));
Minify::addResource('app-scss', [
    'public/build/assets/' . $manifest->{'app.css'}
]);

3. Caching Strategies (SCSS Considerations)

Cache Busting for SCSS Override cache filenames to include SCSS source hashes:

'cache_filename' => 'min_' . sha1_file(public_path('resources/scss/main.scss')),

Versioned SCSS URLs

<link href="{{ Minify::url('scss-bundle', true) }}" rel="stylesheet">

4. Asset Grouping with SCSS

Thematic SCSS Grouping

Minify::addResource('dark-theme', [
    'resources/scss/theme/dark.scss',
    'resources/scss/components/dark/*.scss'
]);
Minify::addResource('light-theme', [
    'resources/scss/theme/light.scss'
]);

Toggle themes dynamically:

if (session('theme') === 'dark') {
    Minify::addResource('active-theme', ['dark-theme']);
} else {
    Minify::addResource('active-theme', ['light-theme']);
}

Integration Tips

Laravel Ecosystem

Blade Directives for SCSS Extend the custom directive to handle SCSS:

Blade::directive('minify', function ($expression) {
    return "<?php echo Minify::url($expression); ?>";
});

Usage in Blade:

<link href="{{ minify('scss-bundle') }}" rel="stylesheet">

Dynamic SCSS Loading via Middleware Load theme-specific SCSS based on user preferences:

public function handle($request, Closure $next) {
    $theme = session('theme', 'light');
    Minify::addResource("theme-{$theme}", [
        "resources/scss/theme/{$theme}.scss"
    ]);
    return $next($request);
}

Performance Optimization

Preload Critical SCSS Add SCSS files to the preload config:

'preload' => [
    'css' => [
        '/css/main.css',
        '/css/theme.css' // Compiled from SCSS
    ]
],

Blade usage:

@foreach(config('minify.preload.css') as $asset)
    <link rel="preload" href="{{ Minify::url($asset) }}" as="style">
@endforeach

Lazy-Load Non-Critical SCSS Exclude lazy-loaded SCSS bundles:

Minify::exclude('js', ['/js/lazy-loader.js']);
Minify::exclude('css', ['/css/lazy-components.css']); // Compiled from SCSS

Debugging & Development

Debug Mode for SCSS Enable debug mode to inspect SCSS preprocessing:
```
MINIFY_DEBUG=true
```
- Outputs unminified SCSS with source paths in URLs:
```
<link href="{{ Minify::url('scss-bundle') }}?debug=true" rel="stylesheet">
```

Gotchas and Tips

Pitfalls

1. SCSS Preprocessing Failures

Problem: SCSS files fail to compile due to syntax errors or missing dependencies (e.g., @import paths).
Fix:
- Validate SCSS files with tools like Sass Lint.
- Ensure @import paths are absolute or resolved correctly:
```
@import "variables"; /* Use full path: @import "../variables.scss"; */
```
- Check scssphp logs in Laravel logs (storage/logs/laravel.log).

2. Backward Compatibility Issues

Problem: Existing CSS files may behave differently when bundled with SCSS files.
Fix:
- Test mixed bundles in a staging environment.
- Use Minify::setDebugMode(true) to compare outputs.
- Isolate SCSS and CSS into separate bundles if conflicts arise.

3. SCSS Variable Conflicts

Problem: SCSS variables in one file override those in another.

Fix:

Use namespaced variables (e.g., $theme-dark-primary).

Load SCSS files in a specific order:

Minify::addResource('theme', [
    'resources/scss/variables.scss', // First
    'resources/scss/theme.scss'     // Then
]);

4. Memory Limits with Large SCSS Files

Problem: SCSS preprocessing fails for files > 5MB due to scssphp memory usage.
Fix:
- Increase PHP memory limit:
```
MEMORY_LIMIT=512M
```
- Split large SCSS files into smaller partials and import them:
```
// _partial1.scss
@import "partial2";
```
- Use mrclay/minify’s streaming option:
```
Minify::setStreaming(true);
```

5. Cache Invalidation for SCSS Changes

Problem: Changes to SCSS files aren’t reflected due to caching.