Adding Assetic versus Encore document

frontend.rst

@@ -61,18 +61,28 @@ Guides
 * :doc:`Adding custom loaders & plugins </frontend/encore/custom-loaders-plugins>`
 * :doc:`Advanced Webpack Configuration </frontend/encore/advanced-config>`
 
-Troubleshooting
-...............
+Issues & Questions
+..................
 
 * :doc:`FAQ & Common Issues </frontend/encore/faq>`
+* :doc:`/frontend/encore/versus-assetic`
 
 Full API
 ........
 
 * `Full API`_: https://github.com/symfony/webpack-encore/blob/master/index.js
 
+Assetic
+-------
+
+Assetic is a pure PHP library that helps to process & optimize your assets (similar
+to Encore). Even though we recommend using Encore, Assetic still works great. For
+a comparison, see :doc:`/frontend/encore/versus-assetic`.
+
+For more about Assetic, see :doc:`/assetic`.
+
 Other Front-End Articles
-........................
+------------------------
 
 .. toctree::
     :hidden:

frontend/encore/versus-assetic.rst

@@ -0,0 +1,56 @@
+Encore Versus Assetic?
+======================
+
+Symfony originally shipped with support for :doc:`Assetic </assetic>`: a
+pure PHP library capable of processing, combining and minifying CSS and JavaScript
+files. And while Encore is now the recommended way or processing your assets, Assetic
+still works well.
+
+So what are the differences between Assetic and Encore?
+
++--------------------------+-------------------------------+-------------------------+
+|                          | Assetic                       | Encore                  +
++--------------------------+-------------------------------+-------------------------+
+| Language                 | Pure PHP, relies on other     | Node.js                 |
+|                          | language tools for some tasks |                         |
++--------------------------+-------------------------------+-------------------------+
+| Combine assets?          | Yes                           | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| Minify assets?           | Yes (when configured)         | Yes (out-of-the-box)    |
++--------------------------+-------------------------------+-------------------------+
+| Process Sass/Less?       | Yes                           | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| Loads JS Modules? [1]_   | No                            | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| Load CSS Deps in JS? [1] | No                            | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| React, Vue.js support?   | No [2]_                       | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| Support                  | Not actively maintained       | Actively maintained     |
++--------------------------+-------------------------------+-------------------------+
+
+.. [1] JavaScript modules allow you to organize your JavaScript into small files
+       called modules and import them:
+
+       .. code-block:: javascript
+
+           // require third-party modules
+           var $ = require('jquery');
+
+           // require your own CoolComponent.js modules
+           var coolComponent = require('./components/CoolComponent');
+
+       Encore (via Webpack) parses these automatically and creates a JavaScript
+       file that contains all needed dependencies. You can even require CSS or
+       images.
+
+.. [2] Assetic has outdated support for React.js only. Encore ships with modern
+       support for React.js, Vue.js, Typescript, etc.
+
+Should I Upgrade from Assetic to Encore
+---------------------------------------
+
+If you already have Assetic working in an application, and haven't needed any of
+the features that Encore offers over Assetic, continuting to use Assetic is fine.
+If you *do* start to need more features, then you might have a business case for
+changing to Encore.