Skip to content

Commit 62f322e

Browse files
weaverryanweaverryan
committed
documenting the new split chunks and Twig helper functions for Encore
1 parent 6984951 commit 62f322e

File tree

9 files changed

+149
-38
lines changed

9 files changed

+149
-38
lines changed

‎frontend.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,9 @@ Adding more Features
5555
Optimizing
5656
..........
5757

58-
* :doc:`Versioning (and the manifest.json file) </frontend/encore/versioning>`
58+
* :doc:`Versioning (and the entrypoints.json/manifest.json files) </frontend/encore/versioning>`
5959
* :doc:`Using a CDN </frontend/encore/cdn>`
60+
* :doc:`/frontend/encore/split-chunks`
6061
* :doc:`Creating a "Shared" entry for re-used modules </frontend/encore/shared-entry>`
6162
* :doc:`/frontend/encore/url-loader`
6263

‎frontend/encore/cdn.rst‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,6 @@ e.g. ``https://my-cool-app.com.global.prod.fastly.net/dashboard.js``.
3636
directly from your web server.
3737

3838
You *do* need to make sure that the ``script`` and ``link`` tags you include on your
39-
pages also use the CDN. Fortunately, the ``manifest.json`` paths are updated to
40-
point to the CDN. In Symfony, as long as you've configured
41-
:doc:`Asset Versioning </frontend/encore/versioning>`, you're done! The ``manifest.json``
42-
file includes the full CDN URL:
43-
44-
.. code-block:: twig
45-
46-
{# Your script/link tags don't need to change at all to support the CDN #}
47-
<script src="{{ asset('build/dashboard.js') }}"></script>
39+
pages also use the CDN. Fortunately, the
40+
:ref:`entrypoints.json <encore-entrypointsjson-simple-description>` paths are updated
41+
to include the full URL to the CDN.

‎frontend/encore/dev-server.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,10 @@ This serves the built assets from a new server at ``http://localhost:8080`` (it
1212
not actually write any files to disk). This means your ``script`` and ``link`` tags
1313
need to change to point to this.
1414

15-
If you've activated the :ref:`manifest.json versioning <load-manifest-files>`
16-
you're done: the paths in your templates will automatically point to the dev server.
15+
If you're using the ``encore_entry_script_tags()`` and ``encore_entry_link_tags()``
16+
Twig shortcuts (or are :ref:`processing your assets through entrypoints.json <load-manifest-files>`_
17+
in some other way), you're done: the paths in your templates will automatically point
18+
to the dev server.
1719

1820
You can also pass options to the ``dev-server`` command: any options that are supported
1921
by the normal `webpack-dev-server`_. For example:

‎frontend/encore/faq.rst‎

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -74,20 +74,15 @@ like ``/myAppSubdir``), you just need to configure that when calling ``Encore.se
7474
+ .setPublicPath('/myAppSubdir/build')
7575
7676
+ // this is now needed so that your manifest.json keys are still `build/foo.js`
77-
+ // i.e. you won't need to change anything in your Symfony app
77+
+ // (which is a file that's used by Symfony's asset function)
7878
+ .setManifestKeyPrefix('build')
7979
;
8080
81-
If you're :ref:`processing your assets through manifest.json <load-manifest-files>`,
82-
you're done! The ``manifest.json`` file will now include the subdirectory in the
83-
final paths:
84-
85-
.. code-block:: json
86-
87-
{
88-
"build/app.js": "/myAppSubdir/build/app.123abc.js",
89-
"build/dashboard.css": "/myAppSubdir/build/dashboard.a4bf2d.css"
90-
}
81+
If you're using the ``encore_entry_script_tags()`` and ``encore_entry_link_tags()``
82+
Twig shortcuts (or are :ref:`processing your assets through entrypoints.json <load-manifest-files>`_
83+
in some other way) you're done! These shortcut methods read from an
84+
:ref:`entrypoints.json <encore-entrypointsjson-simple-description>` file that will
85+
now contain the subdirectory.
9186

9287
"jQuery is not defined" or "$ is not defined"
9388
---------------------------------------------

‎frontend/encore/installation-no-flex.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,4 +97,13 @@ And the new ``assets/css/app.css`` file:
9797
9898
You'll customize and learn more about these file in :doc:`/frontend/encore/simple-example`.
9999

100+
.. caution::
101+
102+
Some of the documentation will use features that are specific to Symfony or
103+
Symfony's `WebpackEncoreBundle`_. These are optional, and are special ways of
104+
pointing to the asset paths generated by Encore that enable features like
105+
:doc:`versioning </frontend/encore/versioning>` and
106+
:doc:`split chunks </frontend/encore/split-chunks>`.
107+
100108
.. _`npm`: https://www.npmjs.com/
109+
.. _WebpackEncoreBundle: https://github.com/symfony/webpack-encore-bundle

‎frontend/encore/shared-entry.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
Creating a Shared Commons Entry
22
===============================
33

4+
.. caution::
5+
6+
While this method still works, see :doc:`/frontend/encore/split-chunks` for
7+
the preferred solution to sharing assets between multiple entry files.
8+
49
Suppose you have multiple entry files and *each* requires ``jquery``. In this
510
case, *each* output file will contain jQuery, slowing down your user's experience.
611
To solve this, you can *extract* the common libraries to a "shared" entry file

‎frontend/encore/simple-example.rst‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,8 @@ To build the assets, run:
7878

7979
Congrats! You now have two new files! Next, add a ``script`` and ``link`` tag
8080
to the new, compiled assets (e.g. ``/build/app.css`` and ``/build/app.js``) to
81-
your layout. In Symfony, use the ``asset()`` helper:
81+
your layout. In Symfony, use the ``encore_entry_script_tags()`` helper from
82+
WebpackEncoreBundle:
8283

8384
.. code-block:: twig
8485
@@ -87,14 +88,41 @@ your layout. In Symfony, use the ``asset()`` helper:
8788
<html>
8889
<head>
8990
<!-- ... -->
90-
<link rel="stylesheet" href="{{ asset('build/app.css') }}">
91+
92+
{% block stylesheets %}
93+
{# will render <link rel="stylesheet" src="/build/app.css"> #}
94+
{{ encore_entry_link_tags('app') }}
95+
{% endblock %}
9196
</head>
9297
<body>
9398
<!-- ... -->
94-
<script src="{{ asset('build/app.js') }}"></script>
99+
100+
{% block javascripts %}
101+
{# will render <script src="/build/app.js"></script> #}
102+
{{ encore_entry_script_tags('app') }}
103+
{% endblock %}
95104
</body>
96105
</html>
97106
107+
.. _encore-entrypointsjson-simple-description:
108+
109+
The ``encore_entry_link_tags()`` and ``encore_entry_script_tags()`` functions
110+
read from an ``entrypoints.json`` file that's generated by Encore to know the exact
111+
filename to render. This file is *especially* useful because you can
112+
:doc:`enable versioning</frontend/versioning>` or
113+
:doc:`point assets to a CDN</frontend/cdn>` without making *any* changes to your
114+
template: the paths in ``entrypoints.json`` will always be the final, correct paths.
115+
116+
If you're *not* using Symfony, you can ignore the ``entrypoints.json`` file and
117+
point to the final, built file directly. ``entrypoints.json`` is only required for
118+
some optional features.
119+
120+
.. versionadded::
121+
122+
The ``encore_entry_link_tags()`` comes from WebpackEncoreBundle and relies
123+
on a feature in Encore that was first introduced in version 0.20.0. Previously,
124+
the ``asset()`` function was used to point directly to the file.
125+
98126
Requiring JavaScript Modules
99127
----------------------------
100128

‎frontend/encore/split-chunks.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
Preventing Duplication by "Splitting" Shared Code into Separate Files
2+
=====================================================================
3+
4+
Suppose you have multiple entry files and *each* requires ``jquery``. In this
5+
case, *each* output file will contain jQuery, making your files much larger than
6+
necessary. To solve this, you can ask webpack to analyze your files and *split* them
7+
into additional files, which will contain "shared" code.
8+
9+
To enable this, call ``splitEntryChunks()``:
10+
11+
.. code-block:: diff
12+
13+
Encore
14+
// ...
15+
16+
// multiple entry files, which probably import the same code
17+
.addEntry('app', './assets/js/app.js')
18+
.addEntry('homepage', './assets/js/homepage.js')
19+
.addEntry('blog', './assets/js/blog.js')
20+
.addEntry('store', './assets/js/store.js')
21+
22+
+ .splitEntryChunks()
23+
24+
25+
Now, each output file (e.g. ``homepage.js``) *may* be split into multiple file
26+
(e.g. ``homepage.js``, ``vendor~homepage.js``). This means that you *may* need to
27+
include *multiple* ``script`` tags (or ``link`` tags for CSS) in your template.
28+
Encore creates an :ref:`entrypoints.json <encore-entrypointsjson-simple-description>`
29+
file that lists exactly which CSS and JavaScript files are needed for each entry.
30+
31+
If you're using the ``encore_entry_link_tags()`` and ``encore_entry_script_tags()``
32+
Twig functions from WebpackEncoreBundle, you don't need to do anything else! These
33+
functions automatically read this file and render as many ``script`` or ``link``
34+
tags as needed:
35+
36+
.. code-block:: twig
37+
38+
{#
39+
May now render multiple script tags:
40+
<script src="/build/homepage.js"></script>
41+
<script src="/build/vendor~homepage.js"></script>
42+
#}
43+
{{ encore_entry_script_tags('homepage') }}
44+
45+
Controlling how Assets are Split
46+
--------------------------------
47+
48+
The logic for *when* and *how* to split the files is controlled by the
49+
`SplitChunksPlugin from Webpack`_. You can control the configuration passed to
50+
this plugin with the ``configureSplitChunks()`` function:
51+
52+
.. code-block:: js
53+
54+
.. code-block:: diff
55+
56+
Encore
57+
// ...
58+
59+
.splitEntryChunks()
60+
+ .configureSplitChunks(function(splitChunks) {
61+
+ // change the configuration
62+
+ splitChunks.minSize = 0;
63+
+ }
64+
65+
- talk about SplitChunksPlugin & how you talk to it in Encore
66+
- also look at the runtime chunk stuff
67+
68+
.. _`SplitChunksPlugin from Webpack`: https://webpack.js.org/plugins/split-chunks-plugin/

‎frontend/encore/versioning.rst‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -20,26 +20,37 @@ ignoring any existing cache:
2020
// ...
2121
+ .enableVersioning()
2222
23-
To link to these assets, Encore creates a ``manifest.json`` file with a map to
24-
the new filenames.
23+
To link to these assets, Encore creates two files ``entrypoints.json`` and
24+
``manifest.json``.
2525

2626
.. _load-manifest-files:
2727

28-
Loading Assets from the manifest.json File
29-
------------------------------------------
28+
Loading Assets from entrypoints.json & manifest.json
29+
----------------------------------------------------
3030

31-
Whenever you run Encore, a ``manifest.json`` file is automatically
32-
created in your ``outputPath`` directory:
31+
Whenever you run Encore, two configuration files are generated: ``entrypoints.json``
32+
and ``manifest.json``. Each file is similar, and contains a map to the final, versioned
33+
filename.
34+
35+
The first file - ``entrypoints.json`` - is used by the ``encore_entry_script_tags()``
36+
and ``encore_entry_link_tags()`` Twig helpers. If you're using these, then your
37+
CSS and JavaScript files will render with the new, versioned filename. If you're
38+
not using Symfony, your app will need to read this file in a similar way.
39+
40+
The ``manifest.json`` file is only needed to get the versioned filename of *other*
41+
files, like font files or image files (though it also contains information about
42+
the CSS and JavaScript files):
3343

3444
.. code-block:: json
3545
3646
{
3747
"build/app.js": "/build/app.123abc.js",
38-
"build/dashboard.css": "/build/dashboard.a4bf2d.css"
48+
"build/dashboard.css": "/build/dashboard.a4bf2d.css",
49+
"build/images/logo.png": "/build/images/logo.3eed42.png"
3950
}
4051
41-
In your app, you need to read this file to dynamically render the correct paths
42-
in your ``script`` and ``link`` tags. If you're using Symfony, just activate the
52+
In your app, you need to read this file if you want to be able to link (e.g. via
53+
an ``img`` tag) to certain assets. If you're using Symfony, just activate the
4354
``json_manifest_file`` versioning strategy in ``config.yml``:
4455

4556
.. code-block:: yaml
@@ -56,9 +67,7 @@ like normal:
5667

5768
.. code-block:: twig
5869
59-
<script src="{{ asset('build/app.js') }}"></script>
60-
61-
<link href="{{ asset('build/dashboard.css') }}" rel="stylesheet" />
70+
<img src="{{ asset('build/images/logo.png') }}">
6271
6372
Learn more
6473
----------

0 commit comments

Comments
 (0)