Getting Started

Minimal Steps for Laravel Integration

Install the Package:
```
composer require nette/assets
```

Register AssetManager in Laravel’s Service Provider:

use Nette\Assets\AssetManager;

public function register()
{
    $this->app->singleton('asset.manager', function ($app) {
        $manager = new AssetManager();
        $manager->setBasePath($app->publicPath());
        $manager->addDirectory($app->publicPath('assets/css'));
        $manager->addDirectory($app->publicPath('assets/js'));
        return $manager;
    });
}

First Use Case: Generate Asset URLs in Controllers/Views

// In a controller
public function index()
{
    $cssUrl = app('asset.manager')->getUrl('main.css');
    return view('home', compact('cssUrl'));
}

<!-- In Blade template -->
<link rel="stylesheet" href="{{ $cssUrl }}">

Font Asset with Crossorigin Support:

$font = new \Nette\Assets\FontAsset('fonts/roboto.woff2');
$font->setCrossorigin('anonymous');
$fontUrl = $font->getUrl();

Where to Look First

AssetManager: Core class for registering directories and generating URLs.
addDirectory(): Method to define asset roots (e.g., public_path('assets')).
getUrl(): Resolves paths with optional versioning.
FontAsset: Specialized class for font assets with crossorigin support.
setVersion(): Enable cache-busting for production.

Implementation Patterns

1. Service Integration with Laravel’s Container

Bind AssetManager as a singleton in AppServiceProvider:

public function register()
{
    $this->app->singleton('asset.manager', function ($app) {
        $manager = new AssetManager();
        $manager->setBasePath($app->publicPath());
        $manager->addDirectory($app->publicPath('assets/css'));
        $manager->addDirectory($app->publicPath('assets/js'));
        $manager->setVersion(config('app.version')); // Optional: Append version query
        return $manager;
    });
}

2. Blade Directives for Cleaner Syntax

Create a custom Blade directive:

// app/Providers/BladeServiceProvider.php
use Illuminate\Support\Facades\Blade;

public function boot()
{
    Blade::directive('asset', function ($expression) {
        return "<?php echo app('asset.manager')->getUrl({$expression}); ?>";
    });
}

Usage in Blade:

<link rel="stylesheet" href="@asset('main.css')">

3. Dynamic Asset Loading by Context

Load assets conditionally based on routes or user roles:

public function index()
{
    $assets = app('asset.manager');
    $cssFiles = ['main.css'];
    if (auth()->check()) {
        $cssFiles[] = 'auth.css';
    }
    return view('home', ['cssUrls' => $assets->getUrlList($cssFiles)]);
}

4. Versioning Strategies

Global Versioning:

$manager->setVersion('1.0'); // Outputs: /css/main.css?v=1.0

Environment-Based Versioning:

if (!app()->isLocal()) {
    $manager->setVersion(config('app.version'));
}

Manual Versioning (e.g., filemtime):

$manager->getUrl("main.css?v=" . filemtime(public_path('assets/css/main.css')));

5. Font Asset Handling

Leverage FontAsset for secure font loading:

// In a controller or service
$font = new \Nette\Assets\FontAsset('fonts/roboto.woff2');
$font->setCrossorigin('anonymous');
$fontUrl = $font->getUrl();

Blade Example:

<link rel="preload" href="{{ $assets->getFontUrl('roboto.woff2', 'anonymous') }}" as="font" crossorigin="anonymous">

6. Integration with Vite (v1.0.4+)

Use ViteMapper for Vite dev server proxying:

$manager = new AssetManager();
$manager->setMapper(new \Nette\Assets\ViteMapper('http://localhost:5173'));
$manager->addDirectory(public_path('resources/js'));

Blade Usage:

<script src="@asset('app.js')"></script>

7. Asset Groups for Namespaced Loading

Organize assets by context (e.g., admin, frontend):

$manager->addDirectory(public_path('assets/admin/css'), 'admin');
$manager->addDirectory(public_path('assets/frontend/js'), 'frontend');

Usage:

$adminCss = $manager->getUrl('styles.css', 'admin');

8. Nonce Support (v1.0.3+)

Add nonce attributes for security:

$manager->setNonce('abc123');
$jsUrl = $manager->getUrl('script.js'); // Outputs: script.js?nonce=abc123

Blade Usage:

<script src="{{ $jsUrl }}" nonce="{{ $manager->getNonce() }}"></script>

Gotchas and Tips

1. Path Resolution Issues

Relative Paths: getUrl() resolves from registered directories, not the current working directory.

// ❌ Fails if 'assets' isn’t registered
$manager->getUrl('../assets/main.css');

// ✅ Correct
$manager->addDirectory(public_path('assets'));
$manager->getUrl('main.css');

Case Sensitivity: Filesystem case-sensitivity (e.g., Main.css vs. main.css) breaks lookups on Linux.

2. Versioning Quirks

Cache Busting: If setVersion() isn’t used, manually append hashes:

$version = md5_file(public_path('assets/css/main.css'));
$manager->getUrl("main.css?v=$version");

Environment Mismatch: Disable versioning in development to avoid broken asset links:

if (!app()->environment('local')) {
    $manager->setVersion(config('app.version'));
}

3. Crossorigin Issues

Missing Attribute: Fonts from external domains require crossorigin:

$font = new FontAsset('https://cdn.example.com/fonts/roboto.woff2');
$font->setCrossorigin('anonymous'); // ❌ Forgotten → Font blocks loading

Debugging: Check the "Font" tab in browser dev tools for blocked requests.

4. Integration with Laravel Mix/Vite

Avoid Duplication: Use nette/assets for path resolution only; let Laravel Mix/Vite handle bundling.

Post-Build Workflow:

Use Mix/Vite to output to public/build/.

$manager->addDirectory(public_path('build'));
$manager->setVersion(config('app.version'));

5. Debugging Tips

Inspect Registered Directories:

dd($manager->getDirectories()); // Verify paths

Resolve Full Paths:

$manager->getFullPath('main.css'); // Debug physical location

Font Asset Validation:

$font = new FontAsset('fonts/roboto.woff2');
dd($font->getUrl(), $font->getCrossorigin());

6. Performance Optimizations

Preload Fonts:

@foreach($assets->getFontUrls(['roboto.woff2']) as $url)
    <link rel="preload" href="{{ $url }}" as="font" crossorigin="anonymous">
@endforeach

Lazy-Load Non-Critical Assets:

<script src="{{ $assets->getUrl('analytics.js') }}" defer></script>

7. Extending the Package

Custom Storage: Implement Nette\Assets\IStorage for S3/Azure:

class S3Storage implements IStorage {
    public function url($path) { /* ... */ }
    public function exists($path) { /* ... */ }
}
$manager->setStorage(new S3Storage());

Subclass FontAsset:

class SecureFontAsset extends FontAsset {
    public function __construct($path) {
        parent::__construct($path);
        $this->setCrossorigin('anonymous');
    }
}

Override Versioning: Extend AssetManager

Assets Laravel Package