Assetic Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require vendor/package-name

Publish the configuration file (if applicable):

php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider"

The SourceMapFilter class is now more flexible with site_url handling. For relative paths in source maps, pass an empty string or null:

use Vendor\PackageName\SourceMapFilter;

$filter = new SourceMapFilter([
    'site_url' => '', // or null
    // other options...
]);

Implementation Patterns

Relative Paths in Source Maps

Use site_url => null or site_url => '' when generating source maps for local development or environments where absolute URLs are unnecessary. This ensures paths in the .map file are relative to the project root.

Integration with Laravel Mix/Webpack

If using Laravel Mix, configure the SourceMapFilter in your webpack.mix.js:

mix.webpackConfig({
    plugins: [
        new SourceMapFilterPlugin({
            site_url: '', // Relative paths
            // other options...
        })
    ]
});

Conditional Configuration

Leverage environment variables to toggle between absolute and relative paths:

$siteUrl = env('APP_URL') ?: null; // Use null for relative paths in local/dev
$filter = new SourceMapFilter(['site_url' => $siteUrl]);

Gotchas and Tips

Empty String vs. Null

Both site_url => '' and site_url => null now work identically, but prefer null for explicit "no URL" intent in code.

Debugging Relative Paths

If source maps fail to resolve, verify:

1. The .map file paths are correct relative to the compiled JS/CSS.
2. No trailing slashes in site_url (though this is now irrelevant with null/'').

Backward Compatibility

This change is fully backward-compatible. Existing configurations with non-empty site_url values remain unchanged.

Testing Locally

For local development, always use site_url => null to avoid hardcoding localhost or 127.0.0.1 in source maps.

// config/package.php
'source_map' => [
    'site_url' => env('APP_URL') ? env('APP_URL') : null,
],