Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 9b53860

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

File tree

Expand file treeCollapse file tree

5 files changed

+284
-162
lines changed
Filter options
Expand file treeCollapse file tree

5 files changed

+284
-162
lines changed

‎frontend/encore/advanced-config.rst

Copy file name to clipboardExpand all lines: frontend/encore/advanced-config.rst
+1-1Lines 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

Copy file name to clipboard
+100Lines 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

Copy file name to clipboard
+12-36Lines 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

Copy file name to clipboardExpand all lines: frontend/encore/shared-entry.rst
+31-29Lines 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-
'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)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.