Advanced Webpack Config

Configuring Watching Options and Polling

Encore provides the method configureWatchOptions() to configure Watching Options when running encore dev --watch or encore dev-server:

1
2
3
4
5

Encore.configureWatchOptions(function(watchOptions) {
    // enable polling and check for changes every 250ms
    // polling is useful when running Encore inside a Virtual Machine
    watchOptions.poll = 250;
});

Defining Multiple Webpack Configurations

Webpack supports passing an array of configurations, which are processed in parallel. Webpack Encore includes a reset() object allowing to reset the state of the current configuration to build a new one:

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
36
37
38

// define the first configuration
Encore
    .setOutputPath('public/build/first_build/')
    .setPublicPath('/build/first_build')
    .addEntry('app', './assets/app.js')
    .addStyleEntry('global', './assets/styles/global.scss')
    .enableSassLoader()
    .autoProvidejQuery()
    .enableSourceMaps(!Encore.isProduction())
;

// build the first configuration
const firstConfig = Encore.getWebpackConfig();

// Set a unique name for the config (needed later!)
firstConfig.name = 'firstConfig';

// reset Encore to build the second config
Encore.reset();

// define the second configuration
Encore
    .setOutputPath('public/build/second_build/')
    .setPublicPath('/build/second_build')
    .addEntry('mobile', './assets/mobile.js')
    .addStyleEntry('mobile', './assets/styles/mobile.less')
    .enableLessLoader()
    .enableSourceMaps(!Encore.isProduction())
;

// build the second configuration
const secondConfig = Encore.getWebpackConfig();

// Set a unique name for the config (needed later!)
secondConfig.name = 'secondConfig';

// export the final configuration as an array of multiple configurations
module.exports = [firstConfig, secondConfig];

When running Encore, both configurations will be built in parallel. If you prefer to build configs separately, pass the --config-name option:

1

$ npm run dev -- --config-name firstConfig

Next, define the output directories of each build:

1
2
3
4
5
6

# config/packages/webpack_encore.yaml
webpack_encore:
    output_path: '%kernel.project_dir%/public/default_build'
    builds:
        firstConfig: '%kernel.project_dir%/public/first_build'
        secondConfig: '%kernel.project_dir%/public/second_build'

Also define the asset manifests for each build:

1
2
3
4
5
6
7
8

# config/packages/assets.yaml
framework:
    assets:
        packages:
            first_build:
                json_manifest_path: '%kernel.project_dir%/public/first_build/manifest.json'
            second_build:
                json_manifest_path: '%kernel.project_dir%/public/second_build/manifest.json'

Finally, use the third optional parameter of the encore_entry_*_tags() functions to specify which build to use:

1
2
3
4
5
6
7

{# Using the entrypoints.json file located in ./public/first_build #}
{{ encore_entry_script_tags('app', null, 'firstConfig') }}
{{ encore_entry_link_tags('global', null, 'firstConfig') }}

{# Using the entrypoints.json file located in ./public/second_build #}
{{ encore_entry_script_tags('mobile', null, 'secondConfig') }}
{{ encore_entry_link_tags('mobile', null, 'secondConfig') }}

Avoid Missing CSS When Rendering Multiple Templates

When you render two or more templates in the same request, such as two emails, you should call the reset() method on the EntrypointLookupInterface interface. To do this, inject the EntrypointLookupInterface interface:

1
2
3
4
5
6
7

public function __construct(EntrypointLookupInterface $entryPointLookup) {}

public function send() {
    $this->twig->render($emailOne);
    $this->entryPointLookup->reset();
    $this->render($emailTwo);
}

If you are using multiple Webpack configurations (e.g. one for the admin and one for emails) you will need to inject the right EntrypointLookupInterface service. Use the following command to find the right service:

1
2
3
4
5
6
7
8
9

$ php bin/console console debug:container entrypoint_lookup

# You will see a result similar to this:
Select one of the following services to display its information:
[0] webpack_encore.entrypoint_lookup_collection
[1] webpack_encore.entrypoint_lookup.cache_warmer
[2] webpack_encore.entrypoint_lookup[_default]
[3] webpack_encore.entrypoint_lookup[admin]
[4] webpack_encore.entrypoint_lookup[email]

In this example, the configuration related to the email configuration is the one called webpack_encore.entrypoint_lookup[email].

To inject this service into your class, use the bind option:

1
2
3
4
5

# config/services.yaml
services:
    _defaults
        bind:
            Symfony\WebpackEncoreBundle\Asset\EntrypointLookupInterface $entryPointLookupEmail: '@webpack_encore.entrypoint_lookup[email]'

Now you can inject your service into your class:

1
2
3
4
5
6
7

public function __construct(EntrypointLookupInterface $entryPointLookupEmail) {}

public function send() {
    $this->twig->render($emailOne);
    $this->entryPointLookupEmail->reset();
    $this->render($emailTwo);
}

Configuring the CSS Loader

Encore provides the configureCssLoader() method to customize how css-loader processes your CSS assets. One common use case is to prevent Webpack from resolving certain URLs.

For instance, if your application serves user-uploaded assets from a specific directory, you'll want Webpack to ignore these paths since they may not exist during the build process:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// Configuring the CSS Loader in Webpack Encore
// Prevent Webpack from resolving certain URLs in CSS files
Encore.configureCssLoader((options) => {
    options.url = {
        filter: (url) => {
            // Ignore URLs beginning with /uploads/
            if (url.startsWith('/uploads/')) {
                return false;
            }

            return true; // Process other URLs as usual
        },
    };
});

Generating a Webpack Configuration Object without using the Command-Line Interface

Ordinarily you would use your webpack.config.js file by calling Encore from the command-line interface. But sometimes, having access to the generated Webpack configuration can be required by tools that don't use Encore (for instance a test-runner such as Karma).

The problem is that if you try generating that Webpack configuration object without using the encore command you will encounter the following error:

1

Error: Encore.setOutputPath() cannot be called yet because the runtime environment doesn't appear to be configured. Make sure you're using the encore executable or call Encore.configureRuntimeEnvironment() first if you're purposely not calling Encore directly.

The reason behind that message is that Encore needs to know a few things before being able to create a configuration object, the most important one being what the target environment is.

To solve this issue you can use configureRuntimeEnvironment. This method must be called from a JavaScript file before requiring webpack.config.js.

For instance:

1
2
3
4
5
6
7

const Encore = require('@symfony/webpack-encore');

// Set the runtime environment
Encore.configureRuntimeEnvironment('dev');

// Retrieve the Webpack configuration object
const webpackConfig = require('./webpack.config');

If needed, you can also pass to that method all the options that you would normally use from the command-line interface:

1
2
3
4
5
6

Encore.configureRuntimeEnvironment('dev-server', {
    // Same options you would use with the
    // CLI utility, with their name in camelCase.
    https: true,
    keepPublicPath: true,
});

Having the full control on Loaders Rules

The method configureLoaderRule() provides a clean way to configure Webpack loaders rules (module.rules, see Configuration).

This is a low-level method. All your modifications will be applied just before pushing the loaders rules to Webpack. It means that you can override the default configuration provided by Encore, which may break things. Be careful when using it.

One use might be to configure the eslint-loader to lint Vue files too. The following code is equivalent:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// Manually
const webpackConfig = Encore.getWebpackConfig();

const eslintLoader = webpackConfig.module.rules.find(rule => rule.loader === 'eslint-loader');
eslintLoader.test = /\.(jsx?|vue)$/;

return webpackConfig;

// Using Encore.configureLoaderRule()
Encore.configureLoaderRule('eslint', loaderRule => {
    loaderRule.test = /\.(jsx?|vue)$/
});

return Encore.getWebpackConfig();

The following loaders are configurable with configureLoaderRule():

• javascript (alias js)
• css
• images (but use configureImageRule() instead)
• fonts (but use configureFontRule() instead)
• sass (alias scss)
• less
• stylus
• svelte
• vue
• eslint
• typescript (alias ts)
• handlebars

Configuring Aliases When Importing or Requiring Modules

The Webpack resolve.alias option allows to create aliases to simplify the import or require of certain modules (e.g. by aliasing commonly used src/ folders). In Webpack Encore you can use this option via the addAliases() method:

1
2
3
4

Encore.addAliases({
    Utilities: path.resolve(__dirname, 'src/utilities/'),
    Templates: path.resolve(__dirname, 'src/templates/')
})

With the above config, you could now import certain modules more concisely:

1
2

-import Utility from '../../utilities/utility';
+import Utility from 'Utilities/utility';

Excluding Some Dependencies from Output Bundles

The Webpack externals option allows to prevent bundling of certain imported packages and instead retrieve those external dependencies at runtime. This feature is mostly useful for JavaScript library developers, so you probably won't need it.

In Webpack Encore you can use this option via the addExternals() method:

1
2
3
4
5
6
7

// this won't include jQuery and React in the output bundles generated
// by Webpack Encore. You'll need to load those dependencies yourself
// (e.g with a `<script>` tag) to make the application or website work.
Encore.addExternals({
    jquery: 'jQuery',
    react: 'react'
})