10000 [WCM] Updating the Encore documentation + New recipe · symfony/symfony-docs@9b53860 · GitHub
[go: up one dir, main page]
Skip to content

Commit 9b53860

Browse files
weaverryanweaverryan
committed
[WCM] Updating the Encore documentation + New recipe
1 parent 7c0714a commit 9b53860

File tree

5 files changed

+284
-162
lines changed

5 files changed

+284
-162
lines changed

‎frontend/encore/advanced-config.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ prefer to build configs separately, pass the ``--config-name`` option:
9393

9494
.. code-block:: terminal
9595
96-
$ yarn run encore dev --config-name firstConfig
96+
$ yarn encore dev --config-name firstConfig
9797
9898
.. _`configuration options`: https://webpack.js.org/configuration/
9999
.. _`Webpack's watchOptions`: https://webpack.js.org/configuration/watch/#watchoptions

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
Encore Installation (without Symfony Flex)
2+
==========================================
3+
4+
.. tip:
5+
6+
If your project uses Symfony Flex, read :doc:`/frontend/encore/installation`
7+
for easier instructions.
8+
9+
Installing Encore
10+
-----------------
11+
12+
Install Encore into your project via Yarn:
13+
14+
.. code-block:: terminal
15+
16+
$ yarn add @symfony/webpack-encore --dev
17+
18+
.. note::
19+
20+
If you prefer to use `npm`_, no problem! Run ``npm install @symfony/webpack-encore --save-dev``.
21+
22+
This command creates (or modifies) a ``package.json`` file and downloads dependencies
23+
into a ``node_modules/`` directory. Yarn also creates/updates a ``yarn.lock``
24+
(called ``package-lock.json`` if you use npm version 5+).
25+
26+
.. tip::
27+
28+
You *should* commit ``package.json`` and ``yarn.lock`` (or ``package-lock.json``
29+
if using npm 5) to version control, but ignore ``node_modules/``.
30+
31+
Creating the webpack.config.js File
32+
-----------------------------------
33+
34+
Next, create a new ``webpack.config.js`` file at the root of your project:
35+
36+
.. code-block:: js
37+
38+
var Encore = require('@symfony/webpack-encore');
39+
40+
Encore
41+
// directory where compiled assets will be stored
42+
.setOutputPath('public/build/')
43+
// public path used by the web server to access the output path
44+
.setPublicPath('/build')
45+
// only needed for CDN's or sub-directory deploy
46+
//.setManifestKeyPrefix('build/')
47+
48+
/*
49+
* ENTRY CONFIG
50+
*
51+
* Add 1 entry for each "page" of your app
52+
* (including one that's included on every page - e.g. "app")
53+
*
54+
* Each entry will result in one JavaScript file (e.g. app.js)
55+
* and one CSS file (e.g. app.css) if you JavaScript imports CSS.
56+
*/
57+
.addEntry('app', './assets/js/app.js')
58+
//.addEntry('page1', './assets/js/page1.js')
59+
//.addEntry('page2', './assets/js/page2.js')
60+
61+
.cleanupOutputBeforeBuild()
62+
.enableSourceMaps(!Encore.isProduction())
63+
// enables hashed filenames (e.g. app.abc123.css)
64+
.enableVersioning(Encore.isProduction())
65+
66+
// uncomment if you use TypeScript
67+
//.enableTypeScriptLoader()
68+
69+
// uncomment if you use Sass/SCSS files
70+
//.enableSassLoader()
71+
72+
// uncomment if you're having problems with a jQuery plugin
73+
//.autoProvidejQuery()
74+
;
75+
76+
module.exports = Encore.getWebpackConfig();
77+
78+
Next, create a new ``assets/js/app.js`` file with some basic JavaScript *and*
79+
import some JavaScript:
80+
81+
.. code-block:: javascript
82+
83+
// assets/js/app.js
84+
85+
require('../css/app.css');
86+
87+
console.log('Hello Webpack Encore');
88+
89+
And the new ``assets/css/app.css`` file:
90+
91+
.. code-block:: css
92+
93+
// assets/css/app.css
94+
body {
95+
background-color: lightgray;
96+
}
97+
98+
You'll customize and learn more about these file in :doc:`/frontend/encore/simple-example`.
99+
100+
.. _`npm`: https://www.npmjs.com/

‎frontend/encore/installation.rst

Lines changed: 12 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,22 @@
1-
Encore Installation
2-
===================
1+
Installing Encore (with Symfony Flex)
2+
=====================================
33

4-
First, make sure you `install Node.js`_ and also the `Yarn package manager`_.
4+
.. tip:
55
6-
Then, install Encore into your project with Yarn:
6+
If your project does **not** use Symfony Flex, read :doc:`/frontend/encore/installation-no-flex`.
77
8-
.. code-block:: terminal
9-
10-
$ yarn add @symfony/webpack-encore --dev
11-
12-
.. note::
13-
14-
If you want to use `npm`_ instead of `yarn`_:
15-
16-
.. code-block:: terminal
17-
18-
$ npm install @symfony/webpack-encore --save-dev
8+
First, make sure you `install Node.js`_ and also the `Yarn package manager`_. Then
9+
run:
1910

20-
.. tip::
21-
22-
If you are using Flex for your project, you can initialize your project for Encore via:
23-
24-
.. code-block:: terminal
25-
26-
$ composer require symfony/webpack-encore-pack
27-
$ yarn install
28-
29-
This will create a ``webpack.config.js`` file, add the ``assets/`` directory, and add ``node_modules/`` to
30-
``.gitignore``.
31-
32-
This command creates (or modifies) a ``package.json`` file and downloads dependencies
33-
into a ``node_modules/`` directory. When using Yarn, a file called ``yarn.lock``
34-
is also created/updated. When using npm 5, a ``package-lock.json`` file is created/updated.
11+
.. code-block:: terminal
3512
36-
.. tip::
13+
$ composer require webpack-encore
14+
$ yarn install
3715
38-
You should commit ``package.json`` and ``yarn.lock`` (or ``package-lock.json``
39-
if using npm 5) to version control, but ignore ``node_modules/``.
16+
This will create a ``webpack.config.js`` file, add the ``assets/`` directory, and
17+
add ``node_modules/`` to ``.gitignore``.
4018

41-
Next, create your ``webpack.config.js`` in :doc:`/frontend/encore/simple-example`!
19+
Nice work! Write your first JavaScript and CSS by reading :doc:`/frontend/encore/simple-example`!
4220

4321
.. _`install Node.js`: https://nodejs.org/en/download/
4422
.. _`Yarn package manager`: https://yarnpkg.com/lang/en/docs/install/
45-
.. _`npm`: https://www.npmjs.com/
46-
.. _`yarn`: https://yarnpkg.com/

‎frontend/encore/shared-entry.rst

Lines changed: 31 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -3,53 +3,55 @@ Creating a Shared Commons Entry
33

44
Suppose you have multiple entry files and *each* requires ``jquery``. In this
55
case, *each* output file will contain jQuery, slowing down your user's experience.
6-
In this case, you can *extract* these common libraries to a "shared" entry file
7-
that's included on every page:
6+
To solve this, you can *extract* the common libraries to a "shared" entry file
7+
that's included on every page.
88

9-
.. code-block:: javascript
9+
Suppose you already have an entry called ``app`` that's included on every page.
10+
Update your code to use ``createSharedEntry()``:
11+
12+
.. code-block:: diff
1013
1114
Encore
1215
// ...
13-
.addEntry('page1', 'assets/js/page1.js')
14-
.addEntry('page2', 'assets/js/page2.js')
15-
16-
// this creates a 'vendor.js' file with jquery and the bootstrap JS module
17-
// these modules will *not* be included in page1.js or page2.js anymore
18-
.createSharedEntry('vendor', [
19-
A851 'jquery',
20-
'bootstrap',
21-
22-
// you can also extract CSS - this will create a 'vendor.css' file
23-
// this CSS will *not* be included in page1.css or page2.css anymore
24-
'bootstrap/scss/bootstrap.scss'
25-
])
16+
- .addEntry('app', 'assets/js/app.js')
17+
+ .createSharedEntry('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')
2621
27-
As soon as you make this change, you need to include two extra JavaScript files
28-
on your page before any other JavaScript file:
22+
As soon as you make this change, you need to include *one* extra JavaScript file
23+
in your layout, *before* ``app.js``:
2924

3025
.. _encore-shared-entry-script:
3126

3227
.. code-block:: twig
3328
34-
<!-- these two files now must be included in every page -->
29+
{# templates/base.html.twig #}
30+
<!-- these two files now must be included on every page -->
3531
<script src="{{ asset('build/manifest.js') }}"></script>
36-
<script src="{{ asset('build/vendor.js') }}"></script>
37-
38-
<!-- here you link to the specific JS files needed by the current page -->
3932
<script src="{{ asset('build/app.js') }}"></script>
4033
41-
<!-- if you extracted some CSS, include vendor.css -->
42-
<link rel="stylesheet" href="{{ asset('build/vendor.css') }}" />
34+
<!-- you can still include page-specific JavaScript, like normal -->
35+
<script src="{{ asset('build/store.js') }}"></script>
36+
37+
<!-- continue including app.css on every page -->
38+
<link rel="stylesheet" href="{{ asset('build/app.css') }}" />
39+
40+
Before making this change, if both ``app.js`` and ``store.js`` require ``jquery``,
41+
then ``jquery`` would be packaged into *both* files, which is wasteful. By making
42+
``app.js`` your "shard" entry, *any* code required by ``app.js`` (like jQuery) will
43+
*no longer* be packaged into any other files. The same is true for any CSS.
4344

44-
The ``vendor.js`` file contains all the common code that has been extracted from
45-
the other files, so it's obvious that it must be included. The other file (``manifest.js``)
46-
is less obvious: it's needed so that Webpack knows how to load those shared modules.
45+
Because ``app.js`` contains all the common code that other entry files depend on,
46+
it's obvious that its script (and link) tag must be on every page. The other file
47+
(``manifest.js``) is less obvious: it's needed so that Webpack knows how to load
48+
these shared modules.
4749

4850
.. tip::
4951

50-
The ``vendor.js`` file works best when its contents are changed *rarely*
52+
The ``app.js`` file works best when its contents are changed *rarely*
5153
and you're using :ref:`long-term caching <encore-long-term-caching>`. Why?
52-
If ``vendor.js`` contains application code that *frequently* changes, then
54+
If ``app.js`` contains application code that *frequently* changes, then
5355
(when using versioning), its filename hash will frequently change. This means
5456
your users won't enjoy the benefits of long-term caching for this file (which
5557
is generally quite large).

0 commit comments

Comments
 (0)
0