Assets Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility:

  • Partial Fit: The package’s core features (versioning, caching, storage abstraction) align well with Laravel’s needs for asset management, but its Nette-centric architecture (e.g., AssetManager singleton, IStorage interface) requires custom Laravel integration. Key strengths include:
    • Cache-busting: Automatic versioning (?v=1.23) resolves Laravel’s stale asset issues in production.
    • Font Optimization: WOFF2 support and crossorigin attributes improve LCP (Core Web Vitals).
    • Nonce Support: Simplifies CSP compliance without manual Blade logic.
    • Storage Agnosticism: Supports local, S3, or custom backends via IStorage, but Laravel-specific adapters (e.g., Flysystem) may need extension.
  • Gaps:
    • No native integration with Laravel Mix/Vite’s mix-manifest.json or Vite’s asset hashing.
    • Lacks Laravel’s asset() helper compatibility; requires custom Blade directives or service methods.
    • Build tool limitation: Not a replacement for asset bundling/minification (e.g., Sass, JS modules).

• Modularity:

  • Decouples asset paths from business logic, reducing technical debt in legacy Laravel apps.
  • Service-oriented: Can be injected into controllers/services (e.g., AssetService) for dynamic asset generation.
  • Blade Integration: Supports directives (e.g., @asset('main.css')) for cleaner templates.

Integration Feasibility

• High for Static Assets:
  • Directly replaces hardcoded Blade paths (e.g., <link href="/css/main.css"> → @asset('main.css')).
  • Enables environment-aware asset handling (e.g., disable versioning in development).
• Medium for Hybrid (Vite/Mix) Setups:
  • Vite Dev Server: Use ViteMapper (v1.0.4+) to proxy requests (e.g., http://localhost:5173).
  • Production Builds: Register Vite/Mix outputs (e.g., public/build/) as asset directories.
  • Limitations:
    • No support for Laravel’s mix() helper or Vite’s @vite() directive.
    • Asset hashing must be manually synchronized between nette/assets and Vite.
• Low for Dynamic Assets:
  • Not designed for runtime-generated assets (e.g., user uploads). Custom IStorage implementations would be required.

Technical Risk

Key Questions

1. Asset Strategy:

   • Are assets static (CSS/JS/fonts) or dynamic (user-generated)? Dynamic assets may require custom storage adapters.
   • Will the package replace all asset references, or only static ones (leaving Vite/Mix for bundles)?

2. Build Tool Synergy:

   • Is Vite/Mix used for bundling? If yes, how will nette/assets handle versioned paths for compiled assets?
   • Should asset hashes be synchronized between Vite and nette/assets (e.g., via mix-manifest.json parsing)?

3. Versioning Approach:

   • Global (e.g., ?v=1.0) or file-based (e.g., ?v=md5-hash)? How will this interact with Laravel’s cache (e.g., config('app.version'))?
   • Should versioning be disabled in development to avoid cache-busting during iterative work?

4. Font and Security:

   • Are fonts self-hosted or CDN-hosted? CORS requirements differ (crossorigin vs. anonymous).
   • Are nonces required for CSP compliance? If so, how will they integrate with Blade (e.g., @asset('script.js')->withNonce())?

5. Performance Trade-offs:

   • Will preloading be implemented for critical fonts/above-the-fold assets?
   • How will asset gzip/compression be handled (e.g., via Laravel’s Accept-Encoding middleware)?

6. Team Adoption:

   • Is the team comfortable with PHP-based asset management vs. JavaScript tools (e.g., Vite)?
   • Are there legacy Blade templates with hardcoded paths that need migration?

7. Scaling Considerations:

   • Will assets be CDN-distributed? Custom storage adapters (e.g., AwsS3Storage) may be needed.
   • How will asset fingerprinting (e.g., for CDN cache invalidation) be managed?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Blade Templates: Replace hardcoded paths with @asset() directives (e.g., @asset('css/main.css')).
  • Service Container: Bind AssetManager as a singleton or resolve via AssetService facade.
  • Middleware: Integrate with Laravel’s middleware stack for CORS headers or nonce injection.
  • Storage: Extend IStorage for Laravel-specific backends (e.g., Flysystem, S3).
• Hybrid Vite/Mix Support:
  • Development: Use ViteMapper to proxy requests to Vite’s dev server.
  • Production: Register Vite/Mix output directories (e.g., public/build/) as asset sources.
• Caching:
  • Leverage Laravel’s cache drivers (e.g., Redis, file) for asset metadata caching.

Migration Path

1. Assessment Phase:
   • Audit existing asset references (Blade, JS, CSS) for hardcoded paths.
   • Identify dependencies on Laravel Mix/Vite for bundling vs. static assets.
2. Pilot Implementation:
   • Start with non-critical assets (e.g., fonts, static CSS/JS).
   • Replace Blade paths with @asset() directives.
   • Configure AssetManager in AppServiceProvider.
3. Hybrid Integration (if using Vite/Mix):
   • Set up ViteMapper for dev proxying.
   • Register Vite/Mix build outputs as asset directories.
4. Full Rollout:
   • Migrate remaining assets; disable versioning in development.
   • Implement font optimization (WOFF2, preloading, crossorigin).
5. Validation:
   • Test asset paths across environments (local, staging, production).
   • Verify Core Web Vitals (LCP, FID) improvements.
   • Ensure CSP compliance with nonces.

Compatibility

• Laravel Versions: Tested with PHP 8.5 (v1.0.5+); ensure compatibility with Laravel 10/11.
• Blade Templates: Requires custom directives (e.g., Blade::directive('asset', fn($expr) => "<?= app('assets')->asset($expr)?>")).
• Vite/Mix: Limited to static assets; dynamic asset generation (e.g., @vite()) requires manual bridging.
• Storage Backends: Extend IStorage for unsupported backends (e.g., DigitalOceanSpaces).

Sequencing

1. Phase 1: Static Assets
   • Replace hardcoded paths with @asset() directives.
   • Configure AssetManager for versioning and caching.
2. Phase 2: Font Optimization
   • Enable WOFF2, preloading, and crossorigin for fonts.
3. Phase 3: Hybrid Vite/Mix (Optional)
   • Integrate ViteMapper for dev proxying.
   • Register Vite/Mix outputs for production.
4. Phase 4: Security Hardening
   • Implement nonces for CSP compliance.
   • Validate CORS