Asset Mapper Laravel Package

Product Decisions This Supports

• Simplifying asset management: Eliminate manual asset versioning (e.g., styles.css?v=1.2) by automating cache-busted filenames (e.g., styles.[hash].css), reducing frontend bugs and improving performance without requiring a full build pipeline.
• Enabling modern JavaScript adoption: Support ES modules (React, Vue, Svelte) via importmap without adopting Webpack/Vite, lowering the barrier for teams transitioning from jQuery/vanilla JS to modern frameworks.
• Build vs. Buy Decision: Justify not adopting Laravel Vite/Mix for projects where static assets + importmap are the only needs, reducing technical debt from over-engineering and avoiding build tool complexity.
• Progressive frontend modernization: Phase in importmap and versioned assets incrementally, starting with non-critical features (e.g., admin panels) before full frontend overhaul.
• Symfony/Laravel hybrid projects: Unify asset handling across Laravel and Symfony components (e.g., Symfony UX, Mercure) by leveraging a shared tooling pattern, reducing duplication in mixed-stack applications.
• Performance optimization: Reduce redundant HTTP requests via importmap-driven module preloading and digested filenames for long-term caching, improving Core Web Vitals without heavy build configurations.

When to Consider This Package

Adopt this package if:

• Your Laravel app only requires static asset versioning + importmap (no bundling, hot-reloading, or source maps).
• You’re migrating from legacy JS to ES modules (React/Vue/Svelte) but lack the resources to adopt a full build pipeline (Vite/Webpack).
• Your team prioritizes simplicity over build tool flexibility (e.g., no expertise in Webpack/Vite configurations).
• You’re using Symfony components (e.g., Symfony UX, Mercure) and want consistent asset handling across Laravel and Symfony stacks.
• You need zero-config asset mapping for projects with hundreds of static files (CSS/JS/images) and want to avoid manual hashing.
• You’re building a PWA or static site where asset versioning and importmap are critical but bundling is unnecessary.

Avoid this package if:

• You’re already using Laravel Vite/Mix (this package is redundant and may conflict with existing asset pipelines).
• Your project requires dynamic asset generation (e.g., SVG sprites, theme-based assets, or runtime-compiled assets).
• You need hot-reloading, source maps, or advanced bundling/optimization (use Vite or Laravel Mix instead).
• Your team lacks Symfony familiarity (configuration assumes Symfony’s FrameworkBundle patterns, requiring Laravel-specific workarounds).
• You’re not using ES modules (importmap is irrelevant for traditional JS or AMD/CommonJS).
• You need Laravel-native integrations (e.g., Blade directives, mix-manifest.json compatibility, or seamless Laravel Mix/Vite integration).
• Your project relies on custom asset pipelines (e.g., Gulp, custom PHP scripts) that conflict with the package’s static mapping approach.

How to Pitch It (Stakeholders)

For Executives

*"This package lets us modernize frontend assets with minimal risk. By automatically generating importmaps and versioned filenames, we:

• Eliminate cache issues (no more stale assets) without manual intervention, improving reliability.
• Enable ES modules (React/Vue/Svelte) without adopting complex build tools like Webpack or Vite, reducing onboarding friction for developers.
• Align with Symfony if we’re using mixed stacks (e.g., Symfony UX), cutting duplication and technical debt. Risk: Low—it’s a drop-in replacement for manual asset management, not a rewrite. We can pilot it for a non-critical feature (e.g., admin dashboard) to validate performance and developer experience before wider adoption."*

For Engineering Leaders

*"AssetMapper addresses two key pain points:

1. Cache busting: Automatically appends hashes to filenames (e.g., app.[hash].js) to ensure long-term caching and avoid stale assets.
2. Importmap support: Enables native ES module loading (e.g., import 'app.js') without a build step, simplifying migration from legacy JS to modern frameworks like React or Vue. Trade-offs:

• Not a bundler: No hot-reloading, source maps, or advanced optimizations (use Vite or Laravel Mix for those).
• Symfony-centric: Requires adapting Symfony’s configuration structure (e.g., config/packages/) in Laravel, which may need custom Laravel service providers or packages.
• Limited Laravel integration: No native Blade helpers or mix-manifest.json support—developers will need to use asset() manually or build wrappers. Recommendation: Use this for static assets + importmap in new projects or non-critical features. Avoid if you’re already using Vite/Mix or need dynamic asset generation."*

For Developers

*"If you’re tired of manually hashing filenames or configuring importmaps, this package automates it:

1. Install: composer require symfony/asset-mapper.
2. Configure: Add to config/app.php (Symfony-style) or create a Laravel service provider to bridge the gap.
3. Run: php artisan asset:map to generate hashed assets + importmap.json. Example Configuration:

// config/app.php (Laravel workaround)
'asset_mapper' => [
    'public_directory' => public_path('build'),
    'mappings' => [
        'js' => [public_path('js')],
        'css' => [public_path('css')],
    ],
],

Usage in Blade:

<!-- No Blade helpers; use asset() manually -->
<link href="{{ asset('build/styles.[hash].css') }}" rel="stylesheet">
<script type="importmap">
  {{ file_get_contents(public_path('build/importmap.json')) }}
</script>
**Limitations**:
- **No Laravel-native helpers**: You’ll need to build wrappers for Blade or use raw `asset()` calls.
- **Conflicts with Vite/Mix**: Choose one pipeline—don’t mix them.
- **Symfony dependencies**: Some features (e.g., `AssetMapperBundle`) may require additional Laravel glue code."*

---

### **For Product Managers**
*"This is a **low-effort upgrade** for teams stuck with:
- Manual asset versioning (e.g., `styles.css?v=1.2`), leading to cache issues.
- No ES module support, blocking adoption of modern frameworks like React or Vue.
**Use case**: Pilot in a **non-critical feature** (e.g., admin panel or marketing site) to test importmap + versioned assets before full rollout. Measure impact on:
- **Developer velocity**: Time saved on manual hashing/configuration.
- **Performance**: Reduced HTTP requests via importmap preloading.
- **Reliability**: Fewer cache-related bugs in production.
**Alternatives**:
- If you need **bundling**, **Vite is still the gold standard**—this package is only for static assets + importmap.
- If you’re using **Symfony**, this integrates natively; for **pure Laravel**, expect some friction."*