Documentation: how to extend Webpack Encore

[cavasinf]

Hi,

The documentation to extending Webpack encore is 2 years old, and it is not following the "best practice" in terms of webpack. I'm explaining why.

Not using relative links:

📖 Documentation:

Your suggestion is to go manually to vendor from app.js ../../vendor/kevinpapst/adminlte-bundle/Resources/assets/admin-lte.

✔️ Use-case

In dev mode, my app is located in my baseBundle so I need to go deeper to access vendor folder: import '../../../../../vendor/kevinpapst/adminlte-bundle/Resources/assets/admin-lte'.

⚠️ Error ⚠️

But in prod mode (the one which import my baseBundle dependency), vendor is not located in the same directory, so my yarn encore production will crash.

Solution

1. Add vendor entry into webpack.config.js Instead of importing your admin-lte.js in the app.js, we can add an entry for webpack:

    .addEntry('adminlte-bundle', './vendor/kevinpapst/adminlte-bundle/Resources/assets/admin-lte.js')

• Add new entry to twig template (JS & CSS) In our base template (that extend AdminLTEBundle main template), add the new entry adminlte-bundle above the app entry.

{% block stylesheets %}
    {{ encore_entry_link_tags('adminlte-bundle') }}
    {{ encore_entry_link_tags('app') }}
{% endblock %}

{% block javascripts %}
    {{ encore_entry_script_tags('adminlte-bundle') }}
    {{ encore_entry_script_tags('app') }}
{% endblock %}

2. Or a sharedEntry

    .createSharedEntry('adminlte-bundle', './vendor/kevinpapst/adminlte-bundle/Resources/assets/admin-lte.js')

Not using Twig functions to import assets:

📖 Documentation:

Add "manually" the <link> HTML attribute

{% block stylesheets %}
  <link rel="stylesheet" href="{{ asset('builds/app.css') }}">
{% endblock %}

{% block javascripts %}
   <script src="{{ asset('builds/app.js') }}"></script>
{% endblock %}

⚠️ Error ⚠️

If we use .splitEntryChunks() from Webpack (Symfony DOC), this can do something I don't really want to live

Solution

Simply use Twig functions instead encore_entry_link_tags and encore_entry_script_tags

Extra

✔️ Use-case

If I need to import Select2 for exemple, I'll import the module in my app.js.

⚠️ Error ⚠️

But this import will override the admin-lte css override for Select2.

Solution

As suggested above, we need to add a new entry that is imported BEFORE your [...]/assets/admin-lte.js

• Js file with imports:

// assets/js/import_modules.js
import 'select2/dist/css/select2.css';

import 'select2';

• Webpack file:

// webpack.config.js

Encore
// ...
    .addEntry('import-modules', './assets/js/import_modules.js')
    .addEntry('adminlte-bundle', './vendor/kevinpapst/adminlte-bundle/Resources/assets/admin-lte.js')
    .addEntry('app', './assets/js/app.js')
// ...

• Add entry in base template :

{% block stylesheets %}
    {{ encore_entry_link_tags('import-modules') }}
    {{ encore_entry_link_tags('adminlte-bundle') }}
    {{ encore_entry_link_tags('app') }}
{% endblock %}

{% block javascripts %}
    {{ encore_entry_script_tags('import-modules') }}
    {{ encore_entry_script_tags('adminlte-bundle') }}
    {{ encore_entry_script_tags('app') }}
{% endblock %}

Note

You can maybe add Select2 in your admin-lte.jsto avoid that simple case 🤔

Thx for reading this ❤️

[kevinpapst]

Thanks for sharing this! I will keep this here and make the post sticky, as it contains important infos which are not yet in the documentation. The docs are meant as quick-starter for newbies and this is a great addition