diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst
index 93ea8e9dc2a..03ef7d61255 100644
--- a/frontend/encore/simple-example.rst
+++ b/frontend/encore/simple-example.rst
@@ -4,10 +4,20 @@ First Example
Imagine you have a simple project with one CSS and one JS file, organized into
an ``assets/`` directory:
-* ``assets/js/main.js``
-* ``assets/css/global.scss``
+* ``assets/js/app.js``
+* ``assets/css/app.scss``
-With Encore, we can easily minify these files, pre-process ``global.scss``
+Let's consider that the project follows the recommended practice of importing
+the CSS files for their associated JavaScript files:
+
+.. code-block:: javascript
+
+ // assets/js/app.js
+ require('../css/app.scss');
+
+ // ...rest of JavaScript code here
+
+With Encore, we can easily minify these files, pre-process ``app.scss``
through Sass and a *lot* more.
Configuring Encore/Webpack
@@ -22,20 +32,17 @@ Inside, use Encore to help generate your Webpack configuration.
var Encore = require('@symfony/webpack-encore');
Encore
- // directory where all compiled assets will be stored
+ // the project directory where all compiled assets will be stored
.setOutputPath('web/build/')
- // what's the public path to this directory (relative to your project's document root dir)
+ // the public path used by the web server to access the previous directory
.setPublicPath('/build')
// empty the outputPath dir before each build
.cleanupOutputBeforeBuild()
- // will output as web/build/app.js
- .addEntry('app', './assets/js/main.js')
-
- // will output as web/build/global.css
- .addStyleEntry('global', './assets/css/global.scss')
+ // will create web/build/app.js and web/build/app.css
+ .addEntry('app', './assets/js/app.js')
// allow sass/scss files to be processed
.enableSassLoader()
@@ -78,7 +85,7 @@ Actually, to use ``enableSassLoader()``, you'll need to install a few
more packages. But Encore will tell you *exactly* what you need.
After running one of these commands, you can now add ``script`` and ``link`` tags
-to the new, compiled assets (e.g. ``/build/global.css`` and ``/build/app.js``).
+to the new, compiled assets (e.g. ``/build/app.css`` and ``/build/app.js``).
In Symfony, use the ``asset()`` helper:
.. code-block:: twig
@@ -88,7 +95,7 @@ In Symfony, use the ``asset()`` helper:
-
+
@@ -119,7 +126,7 @@ Great! Use ``require()`` to import ``jquery`` and ``greet.js``:
.. code-block:: javascript
- // assets/js/main.js
+ // assets/js/app.js
// loads the jquery package from node_modules
var $ = require('jquery');
@@ -136,32 +143,23 @@ That's it! When you build your assets, jQuery and ``greet.js`` will automaticall
be added to the output file (``app.js``). For common libraries like jQuery, you
may want also to :doc:`create a shared entry ` for better performance.
-Requiring CSS Files from JavaScript
------------------------------------
+Multiple JavaScript Entries
+---------------------------
-Above, you created an entry called ``app`` that pointed to ``main.js``:
+The previous example is the best way to deal with SPA (Single Page Applications)
+and very simple applications. However, as your application grows, you'll need to
+define more entries with the JavaScript and CSS code of some specific sections
+(homepage, blog, store, etc.)
.. code-block:: javascript
Encore
// ...
- .addEntry('app', './assets/js/main.js')
+ .addEntry('homepage', './assets/js/homepage.js')
+ .addEntry('blog', './assets/js/blog.js')
+ .addEntry('store', './assets/js/store.js')
;
-Once inside ``main.js``, you can even require CSS files:
-
-.. code-block:: javascript
-
- // assets/js/main.js
- // ...
-
- // a CSS file with the same name as the entry js will be output
- require('../css/main.scss');
-
-Now, both an ``app.js`` **and** an ``app.css`` file will be created. You'll need
-to add a link tag to the ``app.css`` file in your templates:
-
-.. code-block:: diff
-
-
- +
+If those entries include CSS/Sass files (e.g. ``homepage.js`` requires
+``assets/css/homepage.scss``), two files will be generated for each of them
+(e.g. ``build/homepage.js`` and ``build/homepage.css``).