Webpack Assets Bundle Laravel Package

Getting Started

This release is the first usable surface for the bundle, so start with the two docs pages it ships: the bundle configuration reference and the new Twig functions page. Read them before touching templates — the configuration reference is what tells you where the CSS/JS asset lists actually live (previously undocumented, which is why this is the natural entry point).

Minimal path:

1. composer require the bundle, register it (Symfony bundle registration, or a service provider + Twig bridge if you're wiring this into a Laravel app — see Gotchas).
2. Add the bundle config file with your stylesheet and script entries.
3. In your base layout, replace hand-written tags:

   <head>
       {{ print_css_link_tags() }}
   </head>
   <body>
       ...
       {{ print_js_script_tags() }}
   </body>
   

4. Verify the rendered HTML in the browser source, not just the Twig output — the whole point of the change is the markup, so inspect the <link> and <script> tags directly.

First real use case: consolidating a hardcoded <link rel="stylesheet"> block in base.html.twig into configuration, so that per-environment asset sets (dev bundles vs. prod CDN URLs) become a config change instead of a template edit.

Implementation Patterns

Head/body split. The two functions are deliberately separate so CSS stays in <head> and scripts go before </body>. Keep that split in your layout even though it's tempting to call both together.

Config-driven asset lists. Move absolute/relative URLs out of templates into the bundle configuration. Use environment overrides (config/packages/dev/…, config/packages/prod/…) for CDN prefixes, cache-busted filenames, or extra dev-only scripts.

Inject AssetsTagsPrintService for non-Twig rendering. The new service is the seam for contexts where Twig isn't available: transactional email HTML, a cached fragment warmer, a JSON endpoint returning an HTML snippet, or a health/debug page. Inject it and reuse the same tagging logic rather than duplicating <script> strings. This also makes the tag output unit-testable — the release adds tests for exactly this, so mirror their assertions in your own suite.

Per-layout composition. If you have multiple base layouts (admin, public, email), call the functions in each rather than rendering a shared partial that emits tags — partials make ordering surprises harder to trace.

Laravel-side integration. If this is landing in a Laravel app via a Twig bridge, wrap the two functions in Blade equivalents (a small helper or Blade directive that calls the service) so Blade views don't need Twig. Do the wrapping once, in one place.

Gotchas and Tips

Autoescaping will bite you first. These functions return markup, not text. Confirm the Twig extension declares the output as safe HTML (is_safe: html / Markup). If your tags render as escaped literal text on the page, that's the cause — don't paper over it with |raw at every call site, because that hides the real fix and creates an injection footgun.

Check the actual <link> attributes. The release notes describe the output as <link type="stylesheet">, which is not valid HTML — rel="stylesheet" is the required attribute and type is obsolete in HTML5. Render a page and read the source before rolling this out broadly; if the tag is malformed, browsers may silently ignore the stylesheet, which is a miserable bug to chase from "my CSS just doesn't load."

No attribute passthrough (yet). There's no mention of defer, async, integrity, crossorigin, media, or per-asset attributes. If you rely on SRI or deferred scripts, check whether configuration supports it before migrating those tags — otherwise keep the handful of special-case tags hand-written alongside the generated block.

Ordering matters and isn't obvious. Scripts execute in emission order, and dependencies (jQuery before a plugin) must be declared in that order in config. When something breaks after migration, the diff is usually the ordering, not the tag format.

Config/template cache. These functions depend on bundle configuration, so config changes need a cache clear in environments with compiled container/template caching. If a changed asset URL doesn't appear, clear cache before debugging anything else.

Extension point is the service, not the templates. Override or decorate AssetsTagsPrintService (service alias / decoration, or a subclass bound to the same id) to change tag rendering — e.g. add integrity hashes or dedupe entries. Forking the Twig function or copying the template block will break on upgrade.

Deduping is your responsibility until proven otherwise. Calling the print functions twice (e.g. a partial included in two layouts) likely emits duplicate tags. Audit your layout inheritance before assuming the bundle handles it.

Version context. This is v1.1.0 with new features and documentation but no listed breaking changes, so an upgrade from 1.0.x should be safe. The risk is not the upgrade — it's adopting the functions before you've confirmed the emitted markup matches what browsers and your CSP expect.