Developed with love by KnpLabs Hire us for your project!
541

webpack-encore-bundle

by symfony

Symfony integration with Webpack Encore!

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.

Install the bundle with:

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:

# config/packages/webpack_encore.yaml
webpack_encore:
    # The path where Encore is building the assets - i.e. Encore.setOutputPath()
    output_path: '%kernel.project_dir%/public/build'
    # If multiple builds are defined (as shown below), you can disable the default build:
    # output_path: false

    # 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:
        # pass "frontend" as the 3rg arg to the Twig functions
        # {{ encore_entry_script_tags('entry1', null, 'frontend') }}

        # frontend: '%kernel.project_dir%/public/frontend/build'

    # 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

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:

// 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:

{# any template or base layout where you need to include a JavaScript entry #}

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

    {{ encore_entry_script_tags('entry1') }}
{% 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:

<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:

// 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.

Copyright (c) 2004-2018 Fabien Potencier

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
  • bug #74 Reset default EntrypointLookup on exception to fix #21 and #73 (tbmatuka)
    By weaverryan, 6 months ago
  • Reset default EntrypointLookup on exception to fix #21 and #73
    By weaverryan, 6 months ago
  • minor #81 Minor: Use "an" article instead of "a" (bocharsky-bw)
    By weaverryan, 8 months ago
  • bug #84 Web link 4.4 compat (weaverryan)
    By weaverryan, 8 months ago
  • Fixing 5.1 deprecation
    By weaverryan, 8 months ago
  • php-cs
    By weaverryan, 8 months ago
  • Fixing compat with symfony/web-link 4.4 and own impl of Fig link
    By weaverryan, 8 months ago
  • minor #82 Allow Contracts v2 (fabpot)
    By fabpot, 9 months ago
  • Allow Contracts v2
    By web-flow, 9 months ago
  • Minor: Use "an" article instead of "a"
    By web-flow, 9 months ago
  • feature #80 Allow Symfony 5 (nicolas-grekas)
    By weaverryan, 9 months ago
  • Allow Symfony 5
    By nicolas-grekas, 9 months ago
  • minor #78 Fix Travis SYMFONY_REQUIRE config (wouterj)
    By nicolas-grekas, 9 months ago
  • Swap install scripts from before_install & install
    By web-flow, 11 months ago
  • bug #65 [Contracts] Update dependency to use symfony/service-contracts (wbrinkman)
    By weaverryan, 1 year ago
  • bug #71 Autowire defaultBuild argument when it is not disabled (larzuk91)
    By weaverryan, 1 year ago
  • bug #72 Bugfix: Properly add tags to services (Nyholm)
    By weaverryan, 1 year ago
  • Properly add tags to services
    By Nyholm, 1 year ago
  • Autowire defaultBuild argument when it is not disabled
    By larzuk91, 1 year ago
  • Update dependency to use symfony/service-contracts to prevent autoloading clashes with Symfony 4.3
    By , 1 year ago
  • documenting new options and fixing misleading value for cache
    By weaverryan, 1 year ago
  • feature #61 New preload option to automatically set preload Link header for rendered scripts/styles (weaverryan)
    By weaverryan, 1 year ago
  • New preload option to automatically set preload Link header for rendered scripts/styles
    By weaverryan, 1 year ago
  • feature #54 Added strict mode #43 (karser)
    By weaverryan, 1 year ago
  • Added strict mode
    By karser, 1 year ago
  • feature #56 propose fix for CORS issues with missing crossorigin tag (PhilETaylor, weaverryan)
    By weaverryan, 1 year ago
  • Merge branch 'master' into patch-1
    By web-flow, 1 year ago
  • bug #59 Only add alias to EntrypointLookupInterface if default build is enabled (emodric)
    By weaverryan, 1 year ago
  • small docs tweak
    By web-flow, 1 year ago
  • making arg optional for BC
    By web-flow, 1 year ago