Asset Mapper Laravel Package

Product Decisions This Supports

• Eliminate Build Step Overhead: Replace Laravel Mix/Webpack/Vite for projects with simple asset pipelines (e.g., static sites, marketing pages, or prototypes). Reduces devops complexity by removing Node.js dependencies and build steps.

  • Use Case: Internal tools, documentation sites, or low-complexity frontend apps where bundling is overkill.
  • Roadmap Tie: Aligns with "simplify developer workflows" initiatives by reducing toolchain friction.

• Modern JavaScript Adoption Without Bundlers:

  • Enable ES modules (import/export) and package managers (e.g., esm.sh) via importmap generation.
  • Use Case: Teams migrating legacy jQuery apps to modern frameworks (React, Vue) without adopting Webpack.
  • Build vs. Buy: Avoids custom importmap solutions or third-party tools (e.g., Rollup, esbuild).

• Cache-Busting for Static Assets:

  • Automatically version filenames (e.g., app.[hash].js) to invalidate browser caches during deployments.
  • Use Case: Critical for CDN-hosted assets or progressive web apps (PWAs) where stale assets break functionality.
  • Roadmap Tie: Supports "improved performance" goals by reducing soft 404s from cached assets.

• Unified Asset Pipeline:

  • Consolidate CSS/JS/JSON assets into a single workflow, replacing manual ?v=1.2 queries or custom scripts.
  • Use Case: Monolithic Laravel apps with scattered asset management (e.g., some assets use Mix, others are static).
  • Integration: Works alongside Laravel Mix/Vite by treating them as source directories.

• Dev/Prod Parity:

  • Use version_strategy: 'timestamp' in development and hash in production via environment-specific configs.
  • Use Case: Teams struggling with "it works in dev but not prod" due to asset caching.

• Security Hardening:

  • Leverage Symfony’s CSP (Content Security Policy) integration for importmap polyfills (e.g., script-src 'self').
  • Use Case: Compliance-heavy projects (e.g., healthcare, finance) requiring strict CSP headers.

When to Consider This Package

Adopt This Package If:

• Asset Pipeline is Simple:
  • Your project uses static files (CSS, JS, JSON) without complex bundling (e.g., no Sass preprocessing, no TypeScript).
  • Example: Marketing sites, admin dashboards, or internal tools.
• You Need Cache-Busting:
  • Assets are served via CDN or require versioned filenames to avoid stale caches.
• Modern JS is a Priority:
  • You want to use ES modules (import/export) but lack a bundler (e.g., Webpack, Vite).
  • Example: Migrating from jQuery to React/Vue without adopting a full build system.
• Laravel + Symfony Stack:
  • Already using Symfony components (e.g., HTTP Client, UX) and want consistency.
• Reducing DevOps Complexity:
  • Eliminate Node.js dependencies or CI/CD steps for asset compilation.
• Legacy Asset Workflows:
  • Replacing manual ?v=1.2 queries or custom PHP asset scripts with a maintained solution.

Look Elsewhere If:

• Complex Asset Processing:
  • Need Sass/Less preprocessing, TypeScript compilation, or image optimization (use Laravel Mix/Vite/Webpack).
• Advanced Code Splitting:
  • Require dynamic imports or lazy-loading strategies (e.g., React.lazy) beyond static files.
• Monorepo Workflows:
  • Managing assets across multiple repos/frameworks (e.g., Laravel + React Native) may need custom tooling.
• Custom Build Steps:
  • Integrating with tools like PostCSS, Babel, or Pug templates.
• Non-PHP Backends:
  • Using Node.js, Python (Django), or Ruby (Rails) where Symfony integration isn’t native.
• High-Performance Needs:
  • Require tree-shaking, minification, or critical CSS extraction (use Vite or Webpack).

How to Pitch It (Stakeholders)

For Executives (Business/Strategy):

"Simplify Frontend Delivery Without Sacrificing Performance"

• Problem: Frontend builds add complexity (Node.js, Webpack, CI/CD pipelines), slowing down development and deployments.
• Solution: Symfony AssetMapper replaces manual asset versioning and bundling with a zero-config, PHP-native approach.
  • Cache-busting: Automatically versions filenames (e.g., app.[hash].js) to eliminate stale asset issues.
  • Modern JS Support: Enables ES modules (import/export) via importmap, letting teams adopt React/Vue without Webpack.
  • DevOps Savings: Removes Node.js dependencies and build steps, reducing CI/CD time and infrastructure costs.
• ROI:
  • Faster Iterations: Developers spend less time debugging build tools and more time shipping features.
  • Lower Risk: MIT-licensed, battle-tested in Symfony (used by 1M+ sites).
  • Future-Proof: Aligns with web standards (importmap) and Laravel’s ecosystem.
• Ask: "Should we prioritize reducing frontend build complexity to accelerate delivery?"

For Engineering (Technical Deep Dive):

"A Drop-in Replacement for Manual Asset Workflows" Key Value Props:

1. No Build Step:

   • Replaces npm run dev/npm run build with a single php artisan asset-map:dump command.
   • Example: A marketing site with static JS/CSS can go from:

     npm install && npm run build  # 30s → 1GB Node_modules
     

     to:

     php artisan asset-map:dump  # 2s → 0 dependencies
     

2. Importmap for Modern JS:

   • Generates importmap.json to enable:

     <script type="module">
       import React from 'https://esm.sh/react@18';
       import App from './app.js';
     </script>
     

   • Use Case: Migrate jQuery plugins to ES modules without Webpack.

3. Cache-Busting Out of the Box:

   • Files like app.[hash].js auto-version on changes, fixing:
     • Stale CDN caches.
     • "Works in dev but not prod" issues.

4. Laravel Integration:

   • Works alongside Mix/Vite by treating them as source directories.
   • Example config:

     'source_dirs' => [
         resource_path('assets'),       // Static files
         public_path('mix-manifest'), // Laravel Mix outputs
     ],
     

5. Performance:

   • No runtime overhead: Assets are pre-processed at deploy time.
   • CDN-friendly: Versioned filenames enable long-term caching.

Migration Path:

• Phase 1: Replace manual ?v=1.2 queries with hashed filenames.
• Phase 2: Adopt importmap for ES modules in new components.
• Phase 3: Gradually replace Mix/Vite for static assets.

Risks Mitigated:

• Lock-in: Pure PHP component; can coexist with existing tools.
• Maintenance: Actively developed by Symfony (1M+ users).
• Security: Integrates with Symfony’s CSP and nonces.

Call to Action: "Let’s pilot this on [Project X] to eliminate build steps for static assets—reducing deployments from 5m to 2m."