Webpack Encore Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require symfony/webpack-encore-bundle
   

   Ensure WebpackEncoreBundle is registered in config/bundles.php (auto-registered in Symfony Flex projects).

2. Configure Webpack Encore: Update webpack.config.js to use Encore:

   const Encore = require('@symfony/webpack-encore');
   Encore
       .setOutputPath('public/build/')
       .setPublicPath('/build')
       .addEntry('app', './assets/app.js')
       .splitEntryChunks()
       .enableSingleRuntimeChunk()
       .cleanupOutputBeforeBuild()
       .enableBuildNotifications()
       .enableSourceMaps(!Encore.isProduction())
       .enableVersioning(Encore.isProduction())
       .enableSassLoader()
       .enableStimulusBridge('./assets/controllers.json');
   

3. First Use Case: Render dynamic assets in a Twig template:

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

Implementation Patterns

Core Workflows

1. Dynamic Asset Rendering: Use encore_entry_script_tags() and encore_entry_link_tags() to inject Webpack Encore-generated assets dynamically:

   {% block javascripts %}
       {{ encore_entry_script_tags('app') }}
       {{ encore_entry_script_tags('admin') }}
   {% endblock %}
   

2. Conditional Asset Loading: Check if an entrypoint exists before rendering:

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

3. Stimulus Integration: Use Twig filters for Stimulus controllers/actions:

   <div {{ stimulus_controller('hello-controller') }} data-hello-target="world">
       {{ stimulus_action('hello-controller', 'sayHello') }}
   </div>
   

4. Remote entrypoints.json: Host entrypoints.json remotely (e.g., CDN) and configure in config/packages/webpack_encore.yaml:

   webpack_encore:
       entrypoints:
           remote: true
           url: 'https://cdn.example.com/entrypoints.json'
   

5. Custom Attributes: Add custom attributes to script/link tags:

   {{ encore_entry_script_tags('app', { defer: true, 'data-custom': 'value' }) }}
   

Integration Tips

• Cache Warmup: Run php bin/console cache:warmup --env=prod to pre-generate entrypoints.json during deployment.
• Environment-Specific Configs: Use webpack_encore.yaml to override settings per environment:

  when@prod:
      webpack_encore:
          output_path: 'public/build/prod'
          public_path: '/build/prod'
  

• Asset Versioning: Enable versioning in production for cache busting:

  .enableVersioning(Encore.isProduction())
  

Gotchas and Tips

Pitfalls

1. Stimulus Deprecation:

   • stimulus_controller(), stimulus_action(), and stimulus_target() are deprecated. Use symfony/stimulus-bundle instead:

     composer require symfony/stimulus-bundle
     

   • Update Twig templates to use the new bundle’s functions.

2. Sub-Requests:

   • Assets may not reset correctly in sub-requests (e.g., {{ render(controller(...)) }}). Use encore_reset_assets() in parent templates:

     {% encore_reset_assets %}
     

3. Remote entrypoints.json:

   • Ensure CORS headers are configured if hosting remotely. Test with:

     curl -I https://cdn.example.com/entrypoints.json
     

4. PHP Version Mismatch:

   • Minimum PHP 8.1 required for v2.x. Downgrade to v1.x if using PHP < 8.1:

     composer require symfony/webpack-encore-bundle:^1.17
     

5. Double Escaping:

   • Avoid double-escaping in Stimulus DTOs when used with forms. Ensure toArray() is called explicitly:

     {{ form_row(form.password, { attr: stimulus_action('controller', 'action').toArray() }) }}
     

Debugging

• Missing Assets:

  • Verify entrypoints.json exists in public/build/ (or remote URL). Clear cache if needed:

    php bin/console cache:clear
    

  • Check Webpack Encore logs for build errors:

    yarn encore dev --watch
    

• Integrity Hash Errors:

  • Ensure integrity attributes are included in preload tags (fixed in v2.2.0). Update Webpack config:

    .configureBabelPresetEnv((config) => {
        config.useBuiltIns = 'usage';
        config.corejs = 3;
    })
    

Extension Points

1. Custom Entrypoint Lookup: Override the default EntrypointLookup service for custom logic:

   services:
       App\Custom\EntrypointLookup:
           decorates: 'webpack_encore.encore.entrypoint_lookup'
   

2. Twig Extensions: Extend Twig functionality by creating a custom extension:

   class CustomEncoreExtension extends \Twig\Extension\AbstractExtension
   {
       public function getFunctions()
       {
           return [
               new \Twig\TwigFunction('custom_encore_tag', [$this, 'renderCustomTag']),
           ];
       }
   
       public function renderCustomTag(string $entrypoint): string
       {
           // Custom logic
       }
   }
   

   Register in config/packages/twig.yaml:

   twig:
       extensions:
           - App\Custom\EncoreExtension
   

3. Build-Time Hooks: Use Symfony’s event system to hook into Webpack Encore’s build process:

   // config/services.yaml
   services:
       App\EventListener\EncoreBuildListener:
           tags:
               - { name: kernel.event_listener, event: webpack.encore.build.start, method: onBuildStart }