Webpack Encore Bundle Laravel Package

Getting Started

1. Install the bundle via Composer: composer require symfony/webpack-encore-bundle. This auto-registers the bundle and installs webpack-encore dependencies (if using symfony/webpack-encore directly, also install yarn/npm).
2. Configure Encore in webpack.config.js (generated in assets/ by default). Define entrypoints (e.g., app, admin) and configure loaders, CSS preprocessors, etc.
3. Include assets in templates using Twig helpers:

   {{ encore_entry_link_tags('app') }}
   {{ encore_entry_script_tags('app') }}
   

   This automatically loads versioned CSS/JS from public/build/.
4. Start development with:

   yarn encore dev --watch
   # or
   symfony server:run --web-dir=public
   

   The built-in dev server (via encore dev-server) provides hot module replacement (HMR) when running separately.

Implementation Patterns

• Per-controller entrypoints: Define separate entrypoints for admin panels, public pages, and SPA sections (e.g., admin.js, checkout.js) to enable efficient code splitting.
• Dynamic imports: Use import() in JS for lazy-loaded features (e.g., modals, charts), leveraging Webpack’s code splitting without manual chunk naming.
• Environment-aware configs: Use Encore.isProduction() to conditionally enable minification, sourcemaps, or CDN paths in webpack.config.js.
• Static asset handling: Process images/fonts via Encore.copyFiles() for optimized output (e.g., from: './assets/images', to: 'images/[path][name].[hash:8].[ext]').
• Twig extensions integration: Extend encore_entry_script_tags()/encore_entry_link_tags() with custom attributes (e.g., integrity, nonce) using the encore_entry_script_tags('app', { attrs: {'data-turbo-track': 'reload'}}) API.

Gotchas and Tips

• Cache invalidation mismatch: If using HTTP caching (e.g., Varnish), ensure Cache-Control headers are disabled for /build/manifest.json—otherwise, asset requests may use stale filenames.
• Missing entrypoints.json: In prod, always run yarn encore production before deploying; missing manifest causes UnexpectedValueException. Add it to CI build steps.
• Dev server port conflicts: By default, encore dev-server uses port 8080. If blocked, configure via --port=9000 and update Encore.setOutputPath('public/build/') consistently.
• Twig debugging: Enable debug: true in config/packages/webpack_encore.yaml to print raw manifest paths—useful when entries fail to load silently.
• Proxying API routes: When serving SPA frontends via encore dev-server, configure devServer.proxy in webpack.config.js to avoid CORS issues (e.g., proxy /api/* to http://127.0.0.1:8000).
• Custom loaders: Add custom loaders before Encore’s defaults using Encore.configureBabel() or Encore.addLoader() to avoid overriding built-in behavior (e.g., polyfills for legacy browsers via @babel/preset-env).