Webpack Encore Bundle Laravel Package

Getting Started

Reality check first: this is a Symfony bundle, not a Laravel package. composer require in a Laravel app will pull the code down but nothing will register — there is no Kernel, no config/packages/*.yaml, no Twig by default. If you are a Laravel dev reading this because a project (or a client's Symfony app) uses Encore, the day-to-day value is: (a) you can operate a Symfony frontend build confidently, and (b) the entrypoints.json + preload + integrity pattern is directly transplantable to a Laravel Blade directive if you ever swap Vite for Encore.

Minimal steps in the Symfony context where it actually runs:

1. composer require symfony/webpack-encore-bundle (v2 requires PHP 8.1+, Symfony 5.4+; v2.3+ supports Symfony 8).
2. npm install --save-dev @symfony/webpack-encore and run npx encore dev (or encore production) so public/build/entrypoints.json exists. Nothing works until that file exists — the bundle only reads build artifacts.
3. Look first at public/build/entrypoints.json. It is the entire contract: per entry name, a list of js files, css files, and whether a runtime chunk must be loaded first. Every "my JS is 404 / not loaded" issue is diagnosed here.
4. Look second at config/packages/webpack_encore.yaml — output_path must point at the web-visible build dir (%kernel.project_dir%/public/build by default).
5. First use case, in Twig:

{% block stylesheets %}
    {{ encore_entry_link_tags('app') }}
{% endblock %}
...
{% block javascripts %}
    {{ encore_entry_script_tags('app') }}
{% endblock %}

That's the 90% usage. The bundle resolves app from entrypoints.json, renders the runtime chunk first, then the entry files, with defer on scripts.

For a Laravel equivalent, the mental model is @vite('resources/js/app.js'), except that Vite's manifest is per-file while entrypoints.json is per-entry with chunks already split, which is why Encore needed a bundle to do this properly.

Implementation Patterns

Two tags per layout block. Always call encore_entry_link_tags(name) in <head> (CSS) and encore_entry_script_tags(name) at the end of <body>. Don't hand-roll <script src="/build/app.js"> — you will miss the runtime chunk and break splitEntryChunks().

Guard against missing entries. Since v1.14 there is encore_entry_exists('app'), useful for optional/widget entries or when a page might render a bundle that wasn't built:

{% if encore_entry_exists('checkout') %}
    {{ encore_entry_script_tags('checkout') }}
{% endif %}

Note it checks files, not the entry name — an entry declared in webpack.config.js but with no output on disk returns false.

Multiple builds. If you have a separate admin build (a second webpack config with its own outputPath), declare builds: in the bundle config and pass the build name as the last argument. Under the hood EntrypointLookupCollection fans out to one EntrypointLookup per build; the TagRenderer accepts a custom collection if you construct it manually (possible since v1.10).

Custom attributes flow straight through. Since v1.9, both functions take an attributes array/object, and you can also set script_attributes / link_attributes defaults in config. This is the clean hook for CSP nonces and crossorigin:

{{ encore_entry_script_tags('app', null, null, { nonce: csp_nonce() }) }}
{{ encore_entry_link_tags('app', null, null, { crossorigin: 'anonymous' }) }}

CSP / preload integration. The bundle emits Link: </build/app.css>; rel=preload headers via Symfony's WebLink when preload is enabled. v2.2 fixed missing integrity on preload tags and v2.4.2 fixed a duplicated rel — if you're on an older patch and using SRI, upgrade. Laravel analogue: add a small middleware that reads your manifest and pushes Link headers; the pattern transfers well and is a genuine perf win for CSS.

CDN / remote entrypoints. Since v2.2 the entrypoints file can be a remote URL, which lets you point at a CDN-hosted build instead of the local public/build. If you do this, drop cache or set a short TTL, otherwise stale entrypoints survive far too long.

Production hardening. In prod run encore production, enable the bundle's cache (it caches parsed entrypoints) and strict_mode: true so a missing entry throws instead of silently rendering nothing. Wire the cache warmer into your deploy so entrypoints.json is parsed once at build time, not per request.

Gotchas and Tips

• The package is in low-maintenance mode. The README now recommends migrating to Symfony Reprise. Do not build a new frontend strategy on Encore; if you're greenfield, use Vite (Laravel) or Reprise (Symfony). This bundle gets bug/security fixes and dependency bumps only.
• "entrypoints.json does not exist" almost always means the build didn't run, not a bundle bug. Second most common cause: output_path points at assets/ while webpack writes to public/build/. Third: kernel build_dir vs project_dir mismatch (fixed in v2.2, #232 — relevant if you deploy to a read-only filesystem).
• The cache is your friend and your enemy. With cache: true, a rebuilt entrypoints.json may not be picked up until the pool is cleared. When filenames look stale after a deploy, cache:clear before you debug anything else.
• Don't use stimulus_controller() / stimulus_action() / stimulus_target(). They were deprecated in v1.17 and removed in v2.0 — install symfony/stimulus-bundle instead. The v1.17.0 release was broken for anyone upgrading to StimulusBundle (missing service, fixed in 1.17.1); if you're stuck on v1, go to at least 1.17.2.
• Flex recipe upgrade to v2.0 deletes files. assets/controllers.json and assets/bootstrap.js move to the StimulusBundle recipe, so the upgrade looks like a deletion. Restore them or your Stimulus controllers silently stop loading.
• strict_mode off is a silent-failure factory. Without it, missing entries render empty tags and you get a blank page with a 200 status. Turn it on in dev and staging at minimum.
• Extension points for anything custom: decorate webpack_encore.tag_renderer, or build your own service around TagRenderer + a custom EntrypointLookupInterface. That's how teams add SRI, nonces globally, or a "render this entry only if built" helper.
• Laravel translation of all this: if you want the chunk-aware behavior in Laravel without Vite, the pieces are (1) parse entrypoints.json from public/build, (2) a Blade directive that emits the runtime chunk first then entry files, (3) a middleware adding Link: rel=preload with integrity from your SRI manifest. Roughly 100 lines, and you inherit Encore's split-chunk semantics without pulling Symfony into your app.