Webpack Assets Bundle Laravel Package

Getting Started

1. Install the bundle in a Symfony 2.x/3.x project:

   composer require ju1ius/webpack-assets-bundle
   

2. Register it in app/AppKernel.php:

   $bundles = [
       // ...
       new Ju1ius\WebpackAssetsBundle\Ju1iusWebpackAssetsBundle(),
   ];
   

3. Emit a manifest/stats file from webpack during your build. The bundle expects webpack output metadata (typically a stats.json or manifest) so Symfony can resolve hashed filenames:

   webpack --json > web/assets/stats.json
   

   In watch/dev mode, either regenerate this file or point the bundle at the webpack-dev-server.
4. Configure the bundle in app/config/config.yml. Start by reading the bundle README and DependencyInjection/Configuration.php for the exact keys in your version; expect settings for:
   • the manifest/stats file path
   • the webpack output root/public path
   • the dev-server URL for local development
5. Use it in Twig — the first practical use case is replacing hard-coded asset paths:

   <script src="{{ webpack_asset('app.js') }}"></script>
   

   The helper resolves the logical entry name through the manifest and returns the hashed public URL.

Where to look first:

• README.md for the supported webpack version and config shape.
• DependencyInjection/Configuration.php for available options.
• The Twig extension class (under Twig/) for the exact function names and signatures.

Implementation Patterns

Twig-first asset resolution. The normal day-to-day pattern is to treat webpack entry points as logical names in templates and let the bundle resolve them to versioned filenames. Keep templates free of /build/... paths:

<link rel="stylesheet" href="{{ webpack_asset('styles/app.css') }}">
<script src="{{ webpack_asset('scripts/app.js') }}"></script>

Centralize build output. Configure webpack to write into a single public directory (e.g. web/build/) and set the bundle's manifest path to the generated stats file. This keeps Symfony's document root clean and makes it obvious what is generated vs. checked in.

Separate dev and prod behavior. The usual workflow is:

• Development: run webpack-dev-server and configure the bundle to serve assets from it, so hot reload works and Symfony doesn't need a rebuild on every template change.
• Production: run a full webpack build, commit/generate the manifest as part of deployment, and let the bundle read hashed filenames from disk. Warm the Symfony cache after the manifest is written.

Inject the asset service outside Twig. For controllers, console commands, or email templates, inject the bundle's asset-resolving service rather than calling Twig. This lets you reuse the same manifest lookup logic in non-HTML contexts (e.g. generating absolute URLs for transactional emails).

Treat entry points as your contract. Define a small, stable set of webpack entry names (app, admin, vendor) and reference those names everywhere. Avoid referencing individual chunk files directly; chunk names and hashes are implementation details.

Build pipeline integration. Wire the manifest generation into your deploy script, CI, or a Composer post-install hook. The bundle only reads the manifest — it does not run webpack — so a missing build step is a runtime failure waiting to happen.

Cache busting comes for free. Because the manifest maps logical names to hashed filenames, HTTP caching can be aggressive for the build directory. Set long Cache-Control headers on /build/* and let the hashed filenames handle invalidation.

Gotchas and Tips

• This bundle is effectively abandoned. Last release was January 2016, it targets Symfony 2, and it has no dependents. Before adopting, confirm it installs against your PHP/Symfony version; expect to fork or vendor it for Symfony 4+/Flex projects. For new work, prefer Symfony Webpack Encore.
• Webpack version coupling. The manifest/stats format changed significantly across webpack 1 → 2 → 4 → 5. The bundle's parser was written for the webpack of its era. If you use a modern webpack, generate a simple manifest.json via webpack-manifest-plugin and verify the bundle can read it, or add a small adapter.
• Manifest path resolution is relative to the kernel/project root, not the bundle. A manifest that works in dev can fail in prod if the path is resolved differently after cache warmup. Use an absolute path parameter where possible.
• Missing manifest = runtime exception. The bundle typically resolves assets lazily, so a missing or empty manifest may not fail until a template renders. Add a smoke test that renders a page using webpack_asset() in CI.
• Dev-server mode has host/CORS pitfalls. If Symfony is served from localhost:8000 and webpack-dev-server from localhost:8080, asset URLs must be absolute and the dev server must allow cross-origin requests. Check the configured public host, not just the port.
• Don't point production at the dev server. Keep dev-server settings in config_dev.yml and manifest-based settings in config_prod.yml; a mis-merged config can ship dev-server URLs to production.
• Debugging tip: dump the resolved manifest (json_decode(file_get_contents($path), true)) and compare entry names with what your Twig templates request. Most "asset not found" issues are a name mismatch or a manifest generated before the latest build.
• Extension points are limited. The practical customization points are the manifest reader/service and the Twig extension. If you need custom URL generation (CDN prefixes, subresource integrity, absolute URLs for emails), decorate or override those services rather than patching vendor code.
• No integrity/SRI support out of the box. If you need integrity attributes or CDN-aware URL rewriting, plan to add a small Twig extension or service decorator on top.
• Pin the dependency. Given the age and low activity, pin an exact version in composer.json and document the fork/commit you rely on, so a future composer update doesn't silently change behavior.