Contao Encore Bundle

Use the power and simplicity of symfony webpack encore in contao. This bundle let you decide on layout and page level, which encore entries should be loaded. If you want more, you can prepare your bundles define their own encore entries, so never need to manually add or remove encore entries again.

Features

• use symfony encore (symfony/webpack-encore and symfony/webpack-encore-bundle) to enhance your contao assets workflow
• conditionally load your assets only if necessary (entrypoints can be activated in the backend in layout and page setting or added via service from your bundle code (e.g. in a frontend module))
• prepare your bundles to add encore entries when install them and strip assets from the contao global asset arrays

Setup

Prerequisites

• Read the Encore Documentation in order to install Encore and understand the core concepts of Webpack and Symfony Encore.

Recommended:

• In order to add the node dependencies required by composer bundles, you probably want to add them to your project's node dependencies when running webpack in the project's scope. You can use Foxy for this task.

Prepare your project and bundle

Setup your project for encore bundle:

Project setup

Bundle setup

Run Encore

1. Clear your cache

    php vendor/bin/contao-console cache:clear
   

2. Run encore prepare command

    php vendor/bin/contao-console encore:prepare [--skip-entries="entry1,entry2"]
   

3. Run encore to generate the assets

   yarn encore dev

4. Activate encore entries in the contao backend

Usage

Activate encore entries

1. In the contao backend, go to page layout configuration
2. Check "Activate Webpack Encore" and fill the mandatory fields
3. If you have a main project bundle entry containing the main stylesheets, add it as active entry, add also all other entries you want to have activated on every page.
4. For page specific features, you can activate additional entries in page setting (site structure).
   • Be aware, that child pages will inherit settings from their parants
   • Pay attention that you check entries as active (if you want them to be loaded)!
   • If you want an already added entry to be not loaded on an specific page, select it as entry and don't check "active".

Prepare command

    php vendor/bin/contao-console encore:prepare

The prepare command must be executed after every change to the encore entries configuration, e.g. after a composer update or changes to that configurations in your own code.

This generates a file called encore.bundles.js in your project root. This file contains entries for all contao encore compatible bundles that are added by calling encoreBundles.addEntries(); in your webpack.config.js.

Run encore

Run encore to generate/compile your assets.

    yarn encore dev 
    yarn encore dev --watch 
    yarn encore prod

Documentation

Project setup - Prepare your contao project for use with encore and encore bundle

Bundle setup - Add encore bundle support to your bundle

Setup Javascript - Help about setting up your encore entries

Developer Documentation

Configuration Reference