diff --git a/frontend.rst b/frontend.rst index c971f5a67bd..8947cbfd818 100644 --- a/frontend.rst +++ b/frontend.rst @@ -25,6 +25,8 @@ to solve the most common Webpack use cases. Encore is made by `Symfony`_ and works *beautifully* in Symfony applications. But it can easily be used in any application... in any language! +.. _encore-toc: + Encore Documentation -------------------- diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst index 89e9fb2ec0f..4889e40a1e1 100644 --- a/frontend/encore/simple-example.rst +++ b/frontend/encore/simple-example.rst @@ -7,8 +7,8 @@ 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: +With Encore, you should think of CSS as a *dependency* of your JavaScript. This means, +you will *require* whatever CSS you need from inside JavaScript: .. code-block:: javascript @@ -38,9 +38,6 @@ Inside, use Encore to help generate your Webpack configuration. // the public path used by the web server to access the previous directory .setPublicPath('/build') - // empty the outputPath dir before each build - .cleanupOutputBeforeBuild() - // will create web/build/app.js and web/build/app.css .addEntry('app', './assets/js/app.js') @@ -52,6 +49,12 @@ Inside, use Encore to help generate your Webpack configuration. .enableSourceMaps(!Encore.isProduction()) + // empty the outputPath dir before each build + .cleanupOutputBeforeBuild() + + // show OS notifications when builds finish/fail + .enableBuildNotifications() + // create hashed filenames (e.g. app.abc123.css) // .enableVersioning() ; @@ -146,15 +149,16 @@ Great! Use ``require()`` to import ``jquery`` and ``greet.js``: That's it! When you build your assets, jQuery and ``greet.js`` will automatically 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. +may want to :doc:`create a shared entry ` for better +performance. Multiple JavaScript Entries --------------------------- 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.) +and very simple applications. However, as your app grows, you may want to have +page-specific JavaScript or CSS (e.g. homepage, blog, store, etc.). To handle this, +add a new "entry" for each page that needs custom JavaScript or CSS: .. code-block:: javascript @@ -166,5 +170,10 @@ define more entries with the JavaScript and CSS code of some specific sections ; 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 +``assets/css/homepage.scss``), two files will be generated for each: (e.g. ``build/homepage.js`` and ``build/homepage.css``). + +Keep Going! +----------- + +Go back to the :ref:`Encore Top List ` to learn more and add new features.