Best practice for extended twig template which requires js and css?

[wumke]

(Sorry if the info is already somewhere in the docs, I searched but did not find...)
When we have a main template (which is never used on its own but only extended) that requires JS and CSS, how should we handle that correctly when using webpack to require JS and CSS?

A simple example is jQuery: the main template uses it and I also want to use it in the template that extends the main template.

1. We can create a new entry for the main template in webpack.config.js, but when we require the same JS or CSS in the template that extends the main template, does webpack optimize chunks such that it includes 'double requirements by 2 webpack entries in the same page' only once? (I guess not?)
   The pro of this method is that you immediately see which CSS and JS is required for a template and simply cannot forget to add the requirements since they are defined in the template file you are extending.
   The cons are that you need to check all extended twig files when checking which additional stuff to require... and probably also less optimized chunks?

2. Another option is to require a JS and CSS file in the extending template that requires everything needed for the main template. (Note that these files are not referenced in the main template.)
   The pro of this method is that you can track JS and CSS dependencies down to the last template and then require only additional items that are not yet defined.
   The con is that you cannot immediate see what is required by a template since it is not written anywhere in the template.

3. Another option is to check what all templates you extend need and require that in one file for the page, but if the main template would be updated and require additional stuff you must add it as a require in all files that extend the main template (which is a very bad thing)

Maybe... there is another option (did not test yet), sort of combining 1 and 2, by defining a new webpack entry for the main template and include it with encore_entry_link_tags() and encore_entry_script_tags() (method 1) BUT overwriting those blocks when the extending template needs additional stuff (like method 2). That would also allow the main template to be rendered standalone. Also, when no additional requires are needed you do not need to do anything else than extending the template.

What do you guys think about this?

[Lyrkan]

Hi @wumke,

I think you may be overthinking it a bit: Webpack does actually know how to detect common code and put it in separate "shared" files, and the Webpack Encore Bundle allows you to automatically add the right files to your pages.

Let's say that you have some common code in a common.js file, and then multiple pageX.js files for each one of your pages :

// common.js
import * as $ from 'jquery';

$('body').css('background-color', 'red');

// page1.js
import * as $ from 'jquery';

$('body').css('color', 'blue');

// page2.js
console.log('foo');

You'd then create a config file calling the following methods (among others):

// webpack.config.js

Encore
  .enableSingleRuntimeChunk()
  .splitEntryChunks();
  .addEntry('common', './common.js')
  .addEntry('page1', './page1.js')
  .addEntry('page2', './page2.js')

This will generate more JS files than entries:

• runtime.js: Contains the code that "bootstraps" Webpack (this is created when enableSingleRuntimeChunk() is called and you must add it to all the pages that use code generated by Webpack)
• common.js: Code only used in the common entry (the background-color change)
• page1.js: Code only used in the page1 entry (the color change)
• page2.js: Code only used in the page2 entry (the console.log)
• vendors~common~page1.js: Vendors that are shared between page1 and common (jQuery)

Of course this is a really simple example but if, for instance, page1.js and page2.js both imported some common code you would also get something like page1~page2.js... so how can you know what should be imported?

Well, if you open the entrypoints.json file you'll see which files are needed by each entry:

{
  "entrypoints": {
    "common": {
      "js": [
        "/build/runtime.js",
        "/build/vendors~common~page1.js",
        "/build/common.js"
      ]
    },
    "page1": {
      "js": [
        "/build/runtime.js",
        "/build/vendors~common~page1.js",
        "/build/page1.js"
      ]
    },
    "page2": {
      "js": [
        "/build/runtime.js",
        "/build/page2.js"
      ]
    }
  }
}

When you call encore_entry_script_tags() the Webpack Encore Bundle reads this file and knows what <script> tags it should add to your page for the given entry... and if something is shared between two consecutive calls it will only be added by the first one :)

So you could call:

• {{ encore_entry_script_tags('common') }} in a block of your main template
• {{ parent() }} and {{ encore_entry_script_tags('page1') }} in the same block of the template that extends the main one and displays the content of "Page 1"

Which would generate something like:

<script type="text/javascript" src="/build/runtime.js"></script>
<script type="text/javascript" src="/build/vendors~common~page1.js"></script>
<script type="text/javascript" src="/build/commons.js"></script>
<script type="text/javascript" src="/build/page1.js"></script>

[wumke]

'I think you may be overthinking it '

Actually... I was thinking that too at some point, so I decided to post this question :-)

I understand that WebpackEncoreBundle can detect and remove duplicate JS and CSS files, and that Webpack is smart enough to find dependencies that are shared by multiple entries. But the thing is: Webpack does not know which entries will end up together in a page template, only WebpackEncoreBundle does. I think this can mess up optimization, which is why we were guided to WebpackEncoreBundle instead of assetic. In case there are 4 levels of extending templates which each require another javascript, webpack will generate no 'vendors ~ common ~ page1.js' since none of the webpack entries have something in common. In case all of my pages share the first 3 levels of extension (with a different additional script added in the 4th level), their scripts could/should be bundled together. So my pages have a lot in common, but my webpack entries do not...
The docs also mention:

'Page-Specific JavaScript or CSS (Multiple Entries)'

Which is basically the same as saying 'you should create an entry for each page'. What we have is multiple entries for the same page. So to get the most out of Webpack I think that each page should only have one entry. Which means: never create entries for pages that are not shown without being extended. That means that to extend a template with JS and CSS you also have to extend the JS and CSS.

I guess the only way to fully solve this problem is letting the WebpackEncoreBundle detect all possible pages that can be generated in the app with all their entries, so that it can combine entries that never occur alone BEFORE Webpack optimizes them. Webpack should also ensure that no combination of chunks on a single page contain the same code twice. Implementing this would be almost impossible. Seems like using a clone of the good old Assetic, modified with some webpack-like functionality so that dependencies and inheritance can be managed by tags in twig would be perfect to solve this.

[Lyrkan]

In case there are 4 levels of extending templates which each require another javascript, webpack will generate no 'vendors ~ common ~ page1.js' since none of the webpack entries have something in common

I'm not sure to understand what you mean there...

Let's say you have 4 entries for those 4 levels: level0, level1, level2 and level3.

If there is nothing in common (if, for instance, you only use vendorA in level0, vendorB in level1, etc.), then yes, you won't get a shared chunk... but that's expected and not an issue.

If, instead, you have vendorA that is shared by level0 and level1, and vendorB shared by level2 and level3, you'll most likely and up with the following files (names may be a bit different):

• The main chunks (level0.js, level1.js, level2.js and level3.js)
• vendors~level0~level1.js
• vendors~level2~level3.js

And if you import things from a shared_level.js file in level0.js, level1.js and level2.js you'll probably get an additional level0~level1~level2.js file.

In most cases you really don't need to care about that part, only about what you do in each entry (ie. not adding code that's only needed by level3 in level0).

Which is basically the same as saying 'you should create an entry for each page'.

Not necessarily... some people will have an entry per page, others will have an entry per group of pages (for instance an "admin" entry for all admin pages), others will have an entry per "feature" (header, forms, lists, ...) and others will mix all those ideas together.

That choice is entirely up to you based on how you wish to structure your project and what you think is the best decision for it.

[wumke]

If there is nothing in common (if, for instance, you only use vendorA in level0, vendorB in level1, etc.), then yes, you won't get a shared chunk... but that's expected and not an issue.

Indeed, that is the expected Webpack output, but not the optimal output for the page.

I think I can conclude that my actual point is: Webpack is great, WebpackEncoreBundle is great, Twig is great... combining all with inheritance is not always the most ideal use case (and since all are recommended by Symfony community I tought it would be). I'll place myself in the

'others will mix all those ideas together'

box and try a couple of configurations before migrating the whole application (which in this case is very complex application that should be extremely modular and extendable in all ways). Anyway, thanks for your quick replies!

(I'll leave this issue/question open for a while, maybe other people have usefull input on this topic)

[Lyrkan]

Indeed, that is the expected Webpack output, but not the optimal output for the page.

Why couldn't that be the optimal output?

Put differently: imagine that you have those 4 twig templates:

{# common #}
{% block scripts %}
  {{ encore_entry_script_tags('level0') }}
{% endblock %}

{# admin (extends common) #}
{% block scripts %}
  {{ parent() }}
  {{ encore_entry_script_tags('level1') }}
{% endblock %}

{# users (extends admin) #}
{% block scripts %}
  {{ parent() }}
  {{ encore_entry_script_tags('level2') }}
{% endblock %}

{# edit (extends users) #}
{% block scripts %}
  {{ parent() }}
  {{ encore_entry_script_tags('level3') }}
{% endblock %}

You would end-up with a page that contains something like this:

<script type="text/javascript" src="/build/runtime.js"></script>
<script type="text/javascript" src="/build/level0.js"></script>
<script type="text/javascript" src="/build/level1.js"></script>
<script type="text/javascript" src="/build/level2.js"></script>
<script type="text/javascript" src="/build/level3.js"></script>

With:

• level0.js being required by the "common" template (code shared by all pages)
• level1.js being required by the "admin" template (code shared by all admin pages)
• level2.js being required by the "users" template (code shared by the user pages of the admin section)
• level3.js being required by the "edit" template (code needed for that specific page)

Which is the optimal output if no code is shared between those entries.
Do you have an example where it would not work?

[wumke]

Yes, I fully agree that for Webpack (with the info you provide it) this is the only and also optimal solution. However this can change if we extend the application you described with a 'show' page that includes level3-show.js.

In case there are 4 levels of extending templates which each require another javascript, Webpack will generate no 'vendors ~ common ~ page1.js' since none of the webpack entries have something in common. In case all of my pages share the first 3 levels of extension (with a different additional script added in the 4th level), their scripts could/should be bundled together.

That is my example.
And for sure it will 'work' for the end user since all code is included by the 5 script tags... but the optimal solution for the page in this case is combining level 0-2 code into 'level0-level1-level2.js' and include that together with 'level3-show.js' or ' level3-edit.js' or ' level3-showmore.js' and the 'runtime.js'.

I'm not blaming Webpack for doing anything wrong, it simply cannot know that level 0-2 code is never used separately (in fact, by defining an entry you tell Webpack that it could be used separately). I'm just looking for a way to get to the result I just described in a way that is easy to understand and implement. That is why I said that at the moment the only solution to get page-optimized code is to have max 1 Webpack entry on each page. Only then Webpack can generate the most optimized CSS and JS files for the whole application.

It mean it just feels so logical to add a Webpack entry for each level (method 1 in my first post, and I did it also at first)... but doing it that way we kind of fuck up best application optimization chances ourselves. The alternative (method 2) is having an extendable twig template with a not-in-any-way-linked JS file in case the template will never be rendered without being extended. That ensures best optimization but you cannot tell which JS to require by looking at the template code that you are extending (Altough you can add a comment with the file name/path).

It's like choosing to shoot yourself in the left or right foot, you do not want to make that choice.
Having that said, weekend now... time to put those feet on the sofa (and not shooting at them! :p).

[Lyrkan]

In case all of my pages share the first 3 levels of extension (with a different additional script added in the 4th level), their scripts could/should be bundled together.

Well, the premise of that example was that all your pages did not include level 2 (that contains JS needed for the "admin" part) and level 3 (that contains JS needed for the "users" part of your "admin").

If they did you were probably supposed to put the code they contain into level0 and skip level1 and level2 (nothing wrong with that if they are not needed).

And for sure it will 'work' for the end user since all code is included by the 5 script tags... but the optimal solution for the page in this case is combining level 0-2 code into 'level0-level1-level2.js'

Depending on the size of your scripts merging all those files may actually be sub-optimal... Webpack even tends to split entries that get too big into smaller files. Serving multiple files is often a better idea than having users download one big bundle.

[carsonbot]

Thank you for this issue.
There has not been a lot of activity here for a while. Has this been resolved?