Webpack Bundle Laravel Package

Getting Started

This is a Symfony bundle, so the first mental shift for a Laravel developer is that there is no config/app.php provider list and no Vite/Mix helper. Registration happens in config/bundles.php, configuration in config/packages/*.yaml, and the public API is a Twig extension rather than a Blade directive.

1. Install it, and check the PHP constraint first. As of 3.1.0 the only change to the package is the composer.json requirement being widened to 7.4|8.0. Open the released composer.json and read the literal constraint string before you require it — ^7.4 || ^8.0 is fine on modern PHP, but a literal 7.4|8.0 would refuse to install on 8.1+ and you would be stuck on an older tag or a --ignore-platform-req hack:

   composer require freshheads/webpack-bundle:^3.1
   

2. Register the bundle (Symfony Flex may do this automatically):

   // config/bundles.php
   return [
       // ...
       Freshheads\WebpackBundle\FreshheadsWebpackBundle::class => ['all' => true],
   ];
   

3. Point it at the manifest webpack emits. Open the bundle's DependencyInjection/Configuration.php first — that file is the source of truth for the exact config keys, defaults, and whether the path is absolute or relative to %kernel.project_dir%. A typical setup looks like:

   # config/packages/freshheads_webpack.yaml
   freshheads_webpack:
       manifest_path: '%kernel.project_dir%/public/build/manifest.json'
       public_path: '/build'
   

4. Confirm what the Twig function is actually called by reading Twig/ in the bundle (it is a small extension exposing something like webpack_asset('app.js')). Use it in your base layout:

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

   Expected output: /build/app.4f3a1c.js.

The first use case worth wiring end-to-end is your base layout's JS/CSS tags plus a cache-busting check — that is 90% of what this bundle exists to do. 3.1.0 adds nothing here: no dev-server support, no integrity hashes, no entry-tag helpers. The mental model you build on day one is the mental model you keep.

Implementation Patterns

Single manifest, many entries. Treat the manifest as the contract between webpack and Twig. Every entry in webpack.config.js should map to exactly one Twig call. Do not hand-build paths like '/build/' ~ name; that defeats the purpose of the bundle and breaks the moment hashing is enabled.

Dev vs. prod. In development you typically run webpack-dev-server and want URLs pointing at http://localhost:8080/..., while production reads the emitted manifest. Check whether the bundle supports a dev-server base URL config key — 3.1.0 did not add one, so assume it does not. The common workaround is a conditional in your layout:

{% if app.environment == 'dev' %}
    <script