Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • SensioLabs Professional services to help you with Symfony
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Bundles
  4. WebpackEncoreBundle
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Installation
  • Configuration
  • Usage
  • Rendering Multiple Times in a Request (e.g. to Generate a PDF)
  • Custom Attributes on script and link Tags
  • Stimulus / Symfony UX Helper

WebpackEncoreBundle: Symfony integration with Webpack Encore!

Edit this page

WebpackEncoreBundle: Symfony integration with Webpack Encore!

This bundle allows you to use the splitEntryChunks() feature from Webpack Encore by reading an entrypoints.json file and helping you render all of the dynamic script and link tags needed.

Installation

Install the bundle with:

1
$ composer require symfony/webpack-encore-bundle

Configuration

If you're using Symfony Flex, you're done! The recipe will pre-configure everything you need in the config/packages/webpack_encore.yaml file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# config/packages/webpack_encore.yaml
webpack_encore:
    # The path where Encore is building the assets - i.e. Encore.setOutputPath()
    # if you customize this, you will also need to change framework.assets.json_manifest_path (it usually lives in assets.yaml)
    output_path: '%kernel.project_dir%/public/build'
    # If multiple builds are defined (as shown below), you can disable the default build:
    # output_path: false

    # Set attributes that will be rendered on all script and link tags
    script_attributes:
        defer: true
        # referrerpolicy: origin
    # link_attributes:
    #     referrerpolicy: origin

    # if using Encore.enableIntegrityHashes() and need the crossorigin attribute (default: false, or use 'anonymous' or 'use-credentials')
    # crossorigin: 'anonymous'

    # preload all rendered script and link tags automatically via the http2 Link header
    # preload: true

    # Throw an exception if the entrypoints.json file is missing or an entry is missing from the data
    # strict_mode: false

    # if you have multiple builds:
    # builds:
        # frontend: '%kernel.project_dir%/public/frontend/build'

        # pass the build name" as the 3rd argument to the Twig functions
        # {{ encore_entry_script_tags('entry1', null, 'frontend') }}

    # Cache the entrypoints.json (rebuild Symfony's cache when entrypoints.json changes)
    # Available in version 1.2
    # Put in config/packages/prod/webpack_encore.yaml
    # cache: true

If you're not using Flex, enable the bundle manually and copy the config file from above into your project.

Usage

The "Split Chunks" functionality in Webpack Encore is enabled by default with the recipe if you install this bundle using Symfony Flex. Otherwise, enable it manually:

1
2
3
4
5
6
7
8
9
// webpack.config.js
// ...
    .setOutputPath('public/build/')
    .setPublicPath('/build')
    .setManifestKeyPrefix('build/')
    .addEntry('entry1', './assets/some_file.js')

+   .splitEntryChunks()
// ...

When you enable splitEntryChunks(), instead of just needing 1 script tag for entry1.js and 1 link tag for entry1.css, you may now need multiple script and link tags. This is because Webpack "splits" your files into smaller pieces for greater optimization.

To help with this, Encore writes an entrypoints.json file that contains all of the files needed for each "entry".

For example, to render all of the script and link tags for a specific "entry" (e.g. entry1), you can:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{# any template or base layout where you need to include a JavaScript entry #}

{% block javascripts %}
    {{ parent() }}

    {{ encore_entry_script_tags('entry1') }}

    {# or render a custom attribute #}
    {#
    {{ encore_entry_script_tags('entry1', attributes={
        defer: true
    }) }}
    #}
{% endblock %}

{% block stylesheets %}
    {{ parent() }}

    {{ encore_entry_link_tags('entry1') }}
{% endblock %}

Assuming that entry1 required two files to be included - build/vendor~entry1~entry2.js and build/entry1.js, then encore_entry_script_tags() is equivalent to:

1
2
<script src="{{ asset('build/vendor~entry1~entry2.js') }}"></script>
<script src="{{ asset('build/entry1.js') }}"></script>

If you want more control, you can use the encore_entry_js_files() and encore_entry_css_files() methods to get the list of files needed, then loop and create the script and link tags manually.

Rendering Multiple Times in a Request (e.g. to Generate a PDF)

When you render your script or link tags, the bundle is smart enough not to repeat the same JavaScript or CSS file within the same request. This prevents you from having duplicate <link> or <script> tags if you render multiple entries that both rely on the same file.

In some cases, however, you may want to render the script & link tags for the same entry multiple times in a request. For example, if you render multiple Twig templates to create multiple PDF files during a single request.

In that case, before each render, you'll need to "reset" the internal cache so that the bundle re-renders CSS or JS files that it previously rendered. For example, in a controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// src/Controller/SomeController.php
use Symfony\WebpackEncoreBundle\Asset\EntrypointLookupInterface;

class SomeController
{
    public function index(EntrypointLookupInterface $entrypointLookup)
    {
        $entrypointLookup->reset();
        // render a template

        $entrypointLookup->reset();
        // render another template

        // ...
    }
}

If you have multiple builds, you can also autowire Symfony\WebpackEncoreBundle\Asset\EntrypointLookupCollectionInterface and use it to get the EntrypointLookupInterface object for any build.

Custom Attributes on script and link Tags

Custom attributes can be added to rendered script or link in 3 different ways:

  1. Via global config (script_attributes and link_attributes) - see the config example above.
  2. When rendering in Twig - see the attributes option in the docs above.
  3. By listening to the Symfony\WebpackEncoreBundle\Event\RenderAssetTagEvent event. For example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    namespace App\EventSubscriber;
    
    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
    use Symfony\WebpackEncoreBundle\Event\RenderAssetTagEvent;
    
    class ScriptNonceSubscriber implements EventSubscriberInterface
    {
        public static function getSubscribedEvents()
        {
            return [
                RenderAssetTagEvent::class => 'onRenderAssetTag'
            ];
        }
    
        public function onRenderAssetTag(RenderAssetTagEvent $event)
        {
            if ($event->isScriptTag()) {
                $event->setAttribute('nonce', 'lookup nonce');
            }
        }
    }

Stimulus / Symfony UX Helper

Version 1 of this bundle came with stimulus_controller(), stimulus_action() and stimulus_target() Twig functions. These have been removed: use symfony/stimulus-bundle instead.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Measure & Improve Symfony Code Performance

    Measure & Improve Symfony Code Performance

    Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

    Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Denis Kop, a Symfony contributor

    Thanks Denis Kop for being a Symfony contributor

    1 commit • 83 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Meilisearch