Webpack Encore Pack Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require symfony/webpack-encore-pack
   

   This auto-configures Encore for Symfony projects, including Webpack 5+ and Babel integration.

2. First Use Case:

   • Locate webpack.config.js in your project root (auto-generated by the pack).
   • Define entry points in config/packages/encore.yaml:

     encore:
         entrypoints:
             app: ['./assets/app.js']
     

   • Run:

     yarn encore dev --watch
     

   • Verify output in public/build/ (default).

3. Key Files to Review:

   • webpack.config.js: Core Webpack config (entrypoints, loaders, plugins).
   • assets/app.js: Default entry file (replace with your JS).
   • config/packages/encore.yaml: Symfony-specific Encore settings.

Implementation Patterns

Workflows

1. Asset Pipeline:

   • JS/CSS: Use encore.input() in entry files:

     // assets/app.js
     import './styles/app.scss';
     

   • Images/Fonts: Reference via encore.addEntry() or import in JS/SCSS:

     @import '~bootstrap/scss/bootstrap';
     

2. Symfony Integration:

   • Twig Assets: Use {{ encore_entry_link_tags('app') }} in templates.
   • Environment-Specific Builds:

     yarn encore production  # Minified, hashed filenames
     yarn encore dev         # Source maps, unminified
     

3. Modular Architecture:

   • Split entrypoints for feature-based builds:

     encore:
         entrypoints:
             admin: ['./assets/admin.js']
             frontend: ['./assets/frontend.js']
     

4. Shared Config:

   • Extend webpack.config.js for project-specific rules:

     Encore.enableSingleRuntimeChunk()
         .enableSourceMaps(!Encore.isProduction())
         .configureBabel(() => { /* Custom Babel config */ });
     

Gotchas and Tips

Pitfalls

1. Caching Issues:

   • Clear cache after config changes:

     yarn encore production --watch --no-cache
     

   • Symfony cache may need clearing:

     php bin/console cache:clear
     

2. Webpack 5+ Quirks:

   • Asset Paths: Use publicPath in webpack.config.js:

     Encore.setPublicPath('/build');
     

   • Hashing: Production builds append content hashes (e.g., app.abc123.js). Avoid hardcoding asset paths in templates.

3. Symfony-Specific:

   • Kernel Debug: Disable in config/packages/dev/encore.yaml for production-like builds:

     encore:
         kernel_debug: false
     

   • Asset Versioning: Use {{ asset() }} for static files (not managed by Encore).

Debugging

1. Webpack Errors:

   • Check yarn encore dev --verbose for detailed logs.
   • Common fixes:
     • Missing loaders (e.g., sass-loader for SCSS).
     • Incorrect file paths in imports.

2. Symfony Debugging:

   • Verify Twig templates render assets correctly:

     {% if kernel.debug %}
         {{ encore_entry_script_tags('app') }}
     {% else %}
         {{ encore_entry_script_tags('app', 'app-map') }}
     {% endif %}
     

Extension Points

1. Custom Webpack Plugins:

   • Add plugins in webpack.config.js:

     Encore.addPlugin(new CustomPlugin());
     

2. Babel Configuration:

   • Override presets/plugins:

     Encore.configureBabel((config) => {
         config.plugins.push('transform-class-properties');
     });
     

3. PostCSS/Sass:

   • Extend loaders:

     Encore.enablePostCssLoader()
         .enableSassLoader(options => options.set('includePaths', ['node_modules']));
     

4. Environment Variables:

   • Use Encore.getContext() to access Symfony parameters:

     const isDev = Encore.getContext().isProduction === false;