Asset Mapper Laravel Package

Product Decisions This Supports

• Reducing Frontend Technical Debt: Replace manual asset versioning (e.g., ?v=1.2) with automated, hash-based filenames (e.g., styles.[hash].css), eliminating cache-busting errors and reducing frontend bugs without requiring a full build pipeline.
• Accelerating ES Module Adoption: Enable modern JavaScript frameworks (React, Vue, Svelte) via importmap without adopting Webpack/Vite, lowering the barrier for teams transitioning from legacy JS to modular architectures.
• Build vs. Buy Decision: Justify not adopting Laravel Vite/Mix for projects where static assets + importmap are the only needs, avoiding over-engineering and reducing maintenance overhead.
• Progressive Frontend Modernization: Incrementally adopt importmap and versioned assets for non-critical features (e.g., admin panels, documentation sites) before full frontend overhauls, minimizing disruption.
• Unified Asset Handling in Hybrid Stacks: Standardize asset management across Laravel and Symfony components (e.g., Symfony UX, Mercure) by leveraging a shared tooling pattern, reducing duplication in mixed-technology applications.
• Performance Optimization: Improve Core Web Vitals by reducing redundant HTTP requests via importmap-driven module preloading and digested filenames for long-term caching, without heavy build configurations.

When to Consider This Package

Adopt symfony/asset-mapper if:

• Your Laravel app only needs 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 and zero upfront cost. By automatically generating importmaps and versioned filenames, we:

• Eliminate cache issues (no more stale assets) without manual intervention, improving reliability and reducing support tickets.
• Enable ES modules (React/Vue/Svelte) without adopting complex build tools like Webpack or Vite, reducing developer onboarding time by 50%.
• 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) in 2 weeks and scale if successful. ROI: Faster frontend iterations, reduced frontend bugs, and future-proofing for modern JS—all without hiring build tool experts."

For Engineering Leaders

*"This solves two key pain points:

1. Asset Versioning: No more ?v=1.2 hacks—automated hashing ensures long-term caching and eliminates stale asset issues.
2. ES Module Support: Importmap lets us use React/Vue/Svelte without Webpack, reducing build complexity and deployment friction. Trade-offs:

• Not a full replacement for Vite/Mix (no hot-reloading, source maps, or advanced optimizations).
• Requires Symfony-like configuration (may need Laravel wrappers for Blade/Twig). Recommendation: Use for static-heavy projects (docs, admin panels) or as a stopgap while evaluating Vite. Pilot with the Symfony UX team first to validate integration."

For Developers

*"This is Webpack-lite for Laravel:

• Zero config: Drop assets in a folder, and it auto-generates versioned filenames + importmaps.
• No build step: Works with raw ES modules (no bundling).
• Symfony-friendly: If you’re using Symfony components, this plays nicely. Limitations:
• No hot-reloading (refresh to see changes).
• No advanced optimizations (e.g., tree-shaking). How to start:

1. Install via Composer: composer require symfony/asset-mapper.
2. Configure asset_mapper.yaml (or use defaults).
3. Run php bin/console asset-mapper:dump to generate versioned assets. Best for: Simple projects, admin panels, or prototyping modern JS without build tool overhead."