From 381570d057e36f0b3557116fb24607d0ca125a75 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 21 Jul 2017 12:10:35 +0200 Subject: [PATCH 1/3] Reworded some explanations in the basic Webpack Encore example --- frontend/encore/simple-example.rst | 64 ++++++++++++++++++++---------- 1 file changed, 43 insertions(+), 21 deletions(-) diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst index 93ea8e9dc2a..cafab52900f 100644 --- a/frontend/encore/simple-example.rst +++ b/frontend/encore/simple-example.rst @@ -4,10 +4,10 @@ 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`` +With Encore, we can easily minify these files, pre-process ``app.scss`` through Sass and a *lot* more. Configuring Encore/Webpack @@ -22,20 +22,20 @@ 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/js/app.js + .addEntry('js/app', './assets/js/app.js') - // will output as web/build/global.css - .addStyleEntry('global', './assets/css/global.scss') + // will output as web/build/css/app.css + .addStyleEntry('css/app', './assets/css/app.scss') // allow sass/scss files to be processed .enableSassLoader() @@ -78,7 +78,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/css/app.css`` and ``/build/js/app.js``). In Symfony, use the ``asset()`` helper: .. code-block:: twig @@ -88,11 +88,11 @@ In Symfony, use the ``asset()`` helper: - + - + @@ -139,29 +139,51 @@ may want also to :doc:`create a shared entry ` fo Requiring CSS Files from JavaScript ----------------------------------- -Above, you created an entry called ``app`` that pointed to ``main.js``: +Above, you created an entry called ``js/app`` that pointed to ``app.js``: .. code-block:: javascript Encore // ... - .addEntry('app', './assets/js/main.js') + .addEntry('js/app', './assets/js/app.js') ; -Once inside ``main.js``, you can even require CSS files: +Once inside ``app.js``, you can even require CSS files: .. code-block:: javascript - // assets/js/main.js + // assets/js/app.js // ... // a CSS file with the same name as the entry js will be output - require('../css/main.scss'); + require('../css/app.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: +Now, both an ``app.js`` **and** an ``app.css`` file will be created in the +``build/js/`` dir. You'll need to add a link tag to the ``app.css`` file in your +templates: .. code-block:: diff - - + + + + + +This article follows the traditional setup where you have just one main CSS file +and one main JavaScript file. In lots of modern JavaScript applications, it's +common to have one "entry" for each important section (homepage, blog, store, etc.) + +In those application, it's better to just add JavaScript entries in the Webpack +configuration file and import the CSS files from the JavaScript entries, as +shown above: + +.. code-block:: javascript + + Encore + // ... + .addEntry('homepage', './assets/js/homepage.js') + .addEntry('blog', './assets/js/blog.js') + .addEntry('store', './assets/js/store.js') + ; + +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``). From f855793f8a6c6910de18d5b52023f17cd6f63b30 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 21 Jul 2017 12:14:09 +0200 Subject: [PATCH 2/3] Typo --- frontend/encore/simple-example.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst index cafab52900f..e3639adc1b8 100644 --- a/frontend/encore/simple-example.rst +++ b/frontend/encore/simple-example.rst @@ -171,7 +171,7 @@ This article follows the traditional setup where you have just one main CSS file and one main JavaScript file. In lots of modern JavaScript applications, it's common to have one "entry" for each important section (homepage, blog, store, etc.) -In those application, it's better to just add JavaScript entries in the Webpack +In those applications, it's better to just add JavaScript entries in the Webpack configuration file and import the CSS files from the JavaScript entries, as shown above: From 478b93dd361eb2bd84ec208df946fb68a0e8b840 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 7 Aug 2017 10:50:59 +0200 Subject: [PATCH 3/3] More rewords and removed the addStyleEntry() method --- frontend/encore/simple-example.rst | 68 ++++++++++-------------------- 1 file changed, 22 insertions(+), 46 deletions(-) diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst index e3639adc1b8..03ef7d61255 100644 --- a/frontend/encore/simple-example.rst +++ b/frontend/encore/simple-example.rst @@ -7,6 +7,16 @@ an ``assets/`` directory: * ``assets/js/app.js`` * ``assets/css/app.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. @@ -31,11 +41,8 @@ Inside, use Encore to help generate your Webpack configuration. // empty the outputPath dir before each build .cleanupOutputBeforeBuild() - // will output as web/build/js/app.js - .addEntry('js/app', './assets/js/app.js') - - // will output as web/build/css/app.css - .addStyleEntry('css/app', './assets/css/app.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/css/app.css`` and ``/build/js/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,11 +95,11 @@ 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,44 +143,13 @@ 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 ------------------------------------ - -Above, you created an entry called ``js/app`` that pointed to ``app.js``: - -.. code-block:: javascript - - Encore - // ... - .addEntry('js/app', './assets/js/app.js') - ; - -Once inside ``app.js``, you can even require CSS files: - -.. code-block:: javascript - - // assets/js/app.js - // ... - - // a CSS file with the same name as the entry js will be output - require('../css/app.scss'); - -Now, both an ``app.js`` **and** an ``app.css`` file will be created in the -``build/js/`` dir. You'll need to add a link tag to the ``app.css`` file in your -templates: - -.. code-block:: diff - - - + - -This article follows the traditional setup where you have just one main CSS file -and one main JavaScript file. In lots of modern JavaScript applications, it's -common to have one "entry" for each important section (homepage, blog, store, etc.) +Multiple JavaScript Entries +--------------------------- -In those applications, it's better to just add JavaScript entries in the Webpack -configuration file and import the CSS files from the JavaScript entries, as -shown above: +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