JavaScript Bundling — Vite, Webpack, esbuild
debt(d7/e5/b5/t7)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints note automated=no, and the tools listed (lighthouse, webpack-bundle-analyzer) are post-hoc performance/analysis tools rather than pre-deployment guards. Serving unbundled modules or hardcoded filenames won't fail at build time — it silently degrades performance or breaks cache-busting only visible through manual audit or Lighthouse runs.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix points to adopting Laravel's @vite() directive or reading manifest.json, but fixing the common mistakes (unbundled production assets, hardcoded filenames across PHP templates, dist/ in git, CI build pipeline setup) requires changes across multiple PHP templates, build configuration, and CI scripts — beyond a single-line patch but short of a full architectural rework.
Closest to 'persistent productivity tax' (b5). The applies_to context is web broadly, and the bundler choice (Vite vs Webpack vs esbuild) plus the asset manifest integration pattern shapes how every PHP template references JS/CSS assets. Misconfiguration or inconsistency imposes an ongoing tax on deployments and onboarding, but it doesn't fundamentally redefine the entire system's architecture.
Closest to 'serious trap' (t7). The misconception field explicitly states developers believe PHP can serve unbundled ES module files directly — a belief that contradicts how production web performance and HTTP/2 actually behave. The 'obvious' approach (just serve the files) appears to work locally in modern browsers but fails in production at scale. This contradicts assumptions developers carry from other contexts (e.g. simple script tags working fine in small projects).
Also Known As
TL;DR
Explanation
PHP serves static assets (JS, CSS) either directly or via a bundler output. Vite (Rollup-based): instant dev server with HMR, fast production builds — recommended for new projects. Webpack: mature, rich plugin ecosystem, complex config — used in Laravel Mix. esbuild: Go-based, 10-100x faster than Webpack, minimal config. Laravel Vite plugin: integrates Vite with PHP's asset manifests. Bun: JS runtime + bundler. All output a manifest.json (or similar) mapping source files to hashed production filenames PHP uses.
Common Misconception
Why It Matters
Common Mistakes
- Serving unbundled node_modules in production
- Not using the asset manifest for PHP template references
- Committing dist/ folder to git instead of building in CI
Code Examples
<!-- Referencing src file directly — no cache busting, no minification: -->
<script src="/resources/js/app.js"></script><!-- Vite manifest.json: {"resources/js/app.js": {"file": "assets/app.Abc123.js"}} -->
<!-- PHP reads manifest for hashed filename: -->
<?php
$manifest = json_decode(file_get_contents(public_path('build/manifest.json')), true);
$appJs = $manifest['resources/js/app.js']['file'];
?>
<script src="/build/<?= $appJs ?>" type="module"></script>
<!-- Or use Laravel's @vite('resources/js/app.js') directive -->