8000 Adding docs for runtime.js and fixed a few other things · symfony/symfony-docs@53f9ffe · GitHub
[go: up one dir, main page]
Skip to content

Commit 53f9ffe

Browse files
weaverryanweaverryan
committed
Adding docs for runtime.js and fixed a few other things
1 parent 62f322e commit 53f9ffe

File tree

6 files changed

+55
-42
lines changed

6 files changed

+55
-42
lines changed

‎frontend/encore/faq.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -97,9 +97,10 @@ code that you're using. See :doc:`/frontend/encore/legacy-apps` for the fix.
9797
Uncaught ReferenceError: webpackJsonp is not defined
9898
----------------------------------------------------
9999

100-
If you get this error, it's probably because you've just added a :doc:`shared entry </frontend/encore/shared-entry>`
101-
but you *forgot* to add a ``script`` tag for the new ``manifest.js`` file. See the
102-
information about the :ref:`script tags <encore-shared-entry-script>` in that section.
100+
If you get this error, it's probably because you've forgotten to add a ``script``
101+
tag for the ``runtime.js`` file that contains Webpack's runtime. If you're using
102+
the ``encore_entry_script_tags()`` Twig function, this should never happen: the
103+
file script tag is rendered automatically.
103104

104105
This dependency was not found: some-module in ./path/to/file.js
105106
---------------------------------------------------------------

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,10 @@ Next, create a new ``webpack.config.js`` file at the root of your project:
5858
//.addEntry('page1', './assets/js/page1.js')
5959
//.addEntry('page2', './assets/js/page2.js')
6060
61+
// will require an extra script tag for runtime.js
62+
// but, you probably want this, unless you're building a single-page app
63+
.enableSingleRuntimeChunk()
64+
6165
.cleanupOutputBeforeBuild()
6266
.enableSourceMaps(!Encore.isProduction())
6367
// enables hashed filenames (e.g. app.abc123.css)

‎frontend/encore/page-specific-assets.rst

Lines changed: 36 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -15,31 +15,52 @@ a new ``checkout`` entry:
1515
Encore
1616
// an existing entry
1717
.addEntry('app', './assets/js/app.js')
18-
// a global styles entry
19-
.addStyleEntry('global', './assets/css/global.scss')
2018
2119
+ .addEntry('checkout', './assets/js/checkout.js')
2220
;
2321
2422
Inside ``checkout.js``, add or require the JavaScript and CSS you need. Then, just
25-
include a ``script`` tag for ``checkout.js`` on the checkout page (and a ``link``
26-
tag for ``checkout.css`` if you import any CSS).
23+
call the ``encore_entry_link_tags()`` and ``encore_entry_script_tags()`` functions
24+
*only* on the checkout page to include the new ``script`` and ``link`` tags
25+
(if any ``link`` tag is needed):
26+
27+
.. code-block:: twig
28+
29+
{# templates/order/checkout.html.twig #}
30+
{# ... #}
31+
32+
{#
33+
Assuming you're using Symfony's standard base.html.twig setup, add
34+
to the stylesheets and javascript blocks
35+
#}
36+
37+
{% block javascripts %}
38+
{{ parent() }}
39+
40+
{{ encore_entry_script_tags('checkout') }}
41+
{% endblock %}
42+
43+
{% block stylesheets %}
44+
{{ parent() }}
45+
46+
{{ encore_entry_link_tags('checkout') }}
47+
{% endblock %}
2748
2849
Multiple Entries Per Page?
2950
--------------------------
3051

31-
Typically, you should include only *one* JavaScript entry per page. This means
32-
the checkout page will include ``checkout.js``, but will *not* include the
33-
``app.js`` that's used on the other pages. Think of the checkout page as its
34-
own "app", where ``checkout.js`` includes all the functionality you need.
52+
Typically, you should include only *one* JavaScript entry per page. Think of the
53+
checkout page as its own "app", where ``checkout.js`` includes all the functionality
54+
you need.
3555

36-
However, if there is some global JavaScript that you want included on *every*
37-
page, you *can* create an entry that contains that code and include both that
38-
entry *and* your page-specific entry. For example, suppose that the ``app``
39-
entry above contains JavaScript you want on every page. In that case, include
40-
both ``app.js`` and ``checkout.js`` on the checkout page.
56+
However, it's pretty common to need to include some global JavaScript and CSS on
57+
every page. For that reason, it usually makes sense to have one entry (e.g. ``app``)
58+
that contains this global code and is included on every page (i.e. it's included
59+
in the *layout* of your app). This means that you will always have one, global entry
60+
on every page (e.g. ``app``) and you *may* have one page-specific JavaScript and
61+
CSS file from a page-specific entry (e.g. ``checkout``).
4162

4263
.. tip::
4364

44-
Be sure to create a :doc:`shared entry </frontend/encore/shared-entry>` to avoid duplicating
45-
the Webpack bootstrap logic and any shared modules.
65+
Be sure to use split chunks :doc:`shared entry </frontend/encore/split-chunks>`
66+
to avoid duplicating and shared code between your entry files.

‎frontend/encore/shared-entry.rst

Lines changed: 1 addition & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -24,33 +24,13 @@ Update your code to use ``createSharedEntry()``:
2424
.addEntry('blog', './assets/js/blog.js')
2525
.addEntry('store', './assets/js/store.js')
2626
27-
As soon as you make this change, you need to include *one* extra JavaScript file
28-
in your layout, *before* ``app.js``:
29-
30-
.. _encore-shared-entry-script:
31-
32-
.. code-block:: twig
33-
34-
{# templates/base.html.twig #}
35-
<!-- these two files now must be included on every page -->
36-
<script src="{{ asset('build/manifest.js') }}"></script>
37-
<script src="{{ asset('build/app.js') }}"></script>
38-
39-
<!-- you can still include page-specific JavaScript, like normal -->
40-
<script src="{{ asset('build/store.js') }}"></script>
41-
42-
<!-- continue including app.css on every page -->
43-
<link rel="stylesheet" href="{{ asset('build/app.css') }}" />
44-
4527
Before making this change, if both ``app.js`` and ``store.js`` require ``jquery``,
4628
then ``jquery`` would be packaged into *both* files, which is wasteful. By making
4729
``app.js`` your "shared" entry, *any* code required by ``app.js`` (like jQuery) will
4830
*no longer* be packaged into any other files. The same is true for any CSS.
4931

5032
Because ``app.js`` contains all the common code that other entry files depend on,
51-
it's obvious that its script (and link) tag must be on every page. The other file
52-
(``manifest.js``) is less obvious: it's needed so that Webpack knows how to load
53-
these shared modules.
33+
it's obvious that its script (and link) tag must be on every page.
5434

5535
.. tip::
5636

‎frontend/encore/simple-example.rst

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -90,15 +90,21 @@ WebpackEncoreBundle:
9090
<!-- ... -->
9191
9292
{% block stylesheets %}
93-
{# will render <link rel="stylesheet" src="/build/app.css"> #}
93+
<!--
94+
Will render a link tag if your module requires CSS
95+
<link rel="stylesheet" src="/build/app.css">
96+
-->
9497
{{ encore_entry_link_tags('app') }}
9598
{% endblock %}
9699
</head>
97100
<body>
98101
<!-- ... -->
99102
100103
{% block javascripts %}
101-
{# will render <script src="/build/app.js"></script> #}
104+
<!--
105+
Will render app.js & a webpack runtime.js file
106+
<script src="/build/runtime.js"></script>
107+
<script src="/build/app.js"></script>
102108
{{ encore_entry_script_tags('app') }}
103109
{% endblock %}
104110
</body>
@@ -108,7 +114,7 @@ WebpackEncoreBundle:
108114

109115
The ``encore_entry_link_tags()`` and ``encore_entry_script_tags()`` functions
110116
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
117+
filename(s) to render. This file is *especially* useful because you can
112118
:doc:`enable versioning</frontend/versioning>` or
113119
:doc:`point assets to a CDN</frontend/cdn>` without making *any* changes to your
114120
template: the paths in ``entrypoints.json`` will always be the final, correct paths.

‎frontend/encore/split-chunks.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ tags as needed:
3737
3838
{#
3939
May now render multiple script tags:
40+
<script src="/build/runtime.js"></script>
4041
<script src="/build/homepage.js"></script>
4142
<script src="/build/vendor~homepage.js"></script>
4243
#}

0 commit comments

Comments
 (0)
0