feature #14287 [Webpack Encore] Change default assets directory structure (tgalopin)

This PR was submitted for the master branch but it was merged into the 5.1 branch instead.

Discussion
----------

[Webpack Encore] Change default assets directory structure

Adapt the documentation for symfony/recipes#789

Commits
-------

e5aa761 [Webpack Encore] Change default assets directory structure

Author: weaverryan

frontend/encore/advanced-config.rst

@@ -65,8 +65,8 @@ state of the current configuration to build a new one:
     Encore
         .setOutputPath('public/build/first_build/')
         .setPublicPath('/build/first_build')
-        .addEntry('app', './assets/js/app.js')
-        .addStyleEntry('global', './assets/css/global.scss')
+        .addEntry('app', './assets/app.js')
+        .addStyleEntry('global', './assets/styles/global.scss')
         .enableSassLoader()
         .autoProvidejQuery()
         .enableSourceMaps(!Encore.isProduction())
@@ -85,8 +85,8 @@ state of the current configuration to build a new one:
     Encore
         .setOutputPath('public/build/second_build/')
         .setPublicPath('/build/second_build')
-        .addEntry('mobile', './assets/js/mobile.js')
-        .addStyleEntry('mobile', './assets/css/mobile.less')
+        .addEntry('mobile', './assets/mobile.js')
+        .addStyleEntry('mobile', './assets/styles/mobile.less')
         .enableLessLoader()
         .enableSourceMaps(!Encore.isProduction())
     ;

frontend/encore/bootstrap.rst

@@ -18,7 +18,7 @@ a ``global.scss`` file, import it from there:
 
 .. code-block:: scss
 
-    // assets/css/global.scss
+    // assets/styles/global.scss
 
     // customize some Bootstrap variables
     $primary: darken(#428bca, 20%);

frontend/encore/code-splitting.rst

@@ -9,7 +9,7 @@ clicked a link:
 
 .. code-block:: javascript
 
-    // assets/js/app.js
+    // assets/app.js
 
     import $ from 'jquery';
     // a fictional "large" module (e.g. it imports video.js internally)
@@ -27,13 +27,13 @@ the code via AJAX when it's needed:
 
 .. code-block:: javascript
 
-    // assets/js/app.js
+    // assets/app.js
 
     import $ from 'jquery';
 
     $('.js-open-video').on('click', function() {
         // you could start a loading animation here
-    
+
         // use import() as a function - it returns a Promise
         import('./components/VideoPlayer').then(({ default: VideoPlayer }) => {
             // you could stop a loading animation here

frontend/encore/copy-files.rst

@@ -12,7 +12,7 @@ To reference an image tag from inside a JavaScript file, *require* the file:
 
 .. code-block:: javascript
 
-    // assets/js/app.js
+    // assets/app.js
 
     // returns the final, public path to this file
     // path is relative to this file - e.g. assets/images/logo.png

frontend/encore/faq.rst

@@ -116,7 +116,7 @@ But, instead of working, you see an error:
 
     This dependency was not found:
 
-    * respond.js in ./assets/js/app.js
+    * respond.js in ./assets/app.js
 
 Typically, a package will "advertise" its "main" file by adding a ``main`` key to
 its ``package.json``. But sometimes, old libraries won't have this. Instead, you'll

frontend/encore/installation.rst

@@ -79,9 +79,9 @@ is the main config file for both Webpack and Webpack Encore:
          * Each entry will result in one JavaScript file (e.g. app.js)
          * and one CSS file (e.g. app.css) if your JavaScript imports CSS.
          */
-        .addEntry('app', './assets/js/app.js')
-        //.addEntry('page1', './assets/js/page1.js')
-        //.addEntry('page2', './assets/js/page2.js')
+        .addEntry('app', './assets/app.js')
+        //.addEntry('page1', './assets/page1.js')
+        //.addEntry('page2', './assets/page2.js')
 
         // When enabled, Webpack "splits" your files into smaller pieces for greater optimization.
         .splitEntryChunks()
@@ -124,17 +124,17 @@ is the main config file for both Webpack and Webpack Encore:
 
         // uncomment if you use API Platform Admin (composer require api-admin)
         //.enableReactPreset()
-        //.addEntry('admin', './assets/js/admin.js')
+        //.addEntry('admin', './assets/admin.js')
     ;
 
     module.exports = Encore.getWebpackConfig();
 
-Next, open the new ``assets/js/app.js`` file which contains some JavaScript code
+Next, open the new ``assets/app.js`` file which contains some JavaScript code
 *and* imports some CSS:
 
 .. code-block:: javascript
 
-    // assets/js/app.js
+    // assets/app.js
     /*
      * Welcome to your app's main JavaScript file!
      *
@@ -148,13 +148,13 @@ Next, open the new ``assets/js/app.js`` file which contains some JavaScript code
     // Need jQuery? Install it with "yarn add jquery", then uncomment to import it.
     // import $ from 'jquery';
 
-    console.log('Hello Webpack Encore! Edit me in assets/js/app.js');
+    console.log('Hello Webpack Encore! Edit me in assets/app.js');
 
-And the new ``assets/css/app.css`` file:
+And the new ``assets/styles/app.css`` file:
 
 .. code-block:: css
 
-    /* assets/css/app.css */
+    /* assets/styles/app.css */
     body {
         background-color: lightgray;
     }

frontend/encore/shared-entry.rst

@@ -18,11 +18,11 @@ Update your code to use ``createSharedEntry()``:
 
     Encore
         // ...
-    -     .addEntry('app', './assets/js/app.js')
-    +     .createSharedEntry('app', './assets/js/app.js')
-        .addEntry('homepage', './assets/js/homepage.js')
-        .addEntry('blog', './assets/js/blog.js')
-        .addEntry('store', './assets/js/store.js')
+    -     .addEntry('app', './assets/app.js')
+    +     .createSharedEntry('app', './assets/app.js')
+        .addEntry('homepage', './assets/homepage.js')
+        .addEntry('blog', './assets/blog.js')
+        .addEntry('store', './assets/store.js')
 
 Before making this change, if both ``app.js`` and ``store.js`` require ``jquery``,
 then ``jquery`` would be packaged into *both* files, which is wasteful. By making

frontend/encore/simple-example.rst

@@ -4,8 +4,8 @@ Encore: Setting up your Project
 After :doc:`installing Encore </frontend/encore/installation>`, your app already has one
 CSS and one JS file, organized into an ``assets/`` directory:
 
-* ``assets/js/app.js``
-* ``assets/css/app.css``
+* ``assets/app.js``
+* ``assets/styles/app.css``
 
 With Encore, think of your ``app.js`` file like a standalone JavaScript
 application: it will *require* all of the dependencies it needs (e.g. jQuery or React),
@@ -14,7 +14,7 @@ application: it will *require* all of the dependencies it needs (e.g. jQuery or
 
 .. code-block:: javascript
 
-    // assets/js/app.js
+    // assets/app.js
     // ...
 
     import '../css/app.css';
@@ -43,14 +43,14 @@ of your project. It already holds the basic config you need:
         // public path used by the web server to access the output path
         .setPublicPath('/build')
 
-        .addEntry('app', './assets/js/app.js')
+        .addEntry('app', './assets/app.js')
 
         // ...
     ;
 
     // ...
 
-The *key* part is ``addEntry()``: this tells Encore to load the ``assets/js/app.js``
+The *key* part is ``addEntry()``: this tells Encore to load the ``assets/app.js``
 file and follow *all* of the ``require()`` statements. It will then package everything
 together and - thanks to the first ``app`` argument - output final ``app.js`` and
 ``app.css`` files into the ``public/build`` directory.
@@ -115,7 +115,7 @@ can do most of the work for you:
 .. _encore-entrypointsjson-simple-description:
 
 That's it! When you refresh your page, all of the JavaScript from
-``assets/js/app.js`` - as well as any other JavaScript files it included - will
+``assets/app.js`` - as well as any other JavaScript files it included - will
 be executed. All the CSS files that were required will also be displayed.
 
 The ``encore_entry_link_tags()`` and ``encore_entry_script_tags()`` functions
@@ -143,7 +143,7 @@ files. First, create a file that exports a function:
 
 .. code-block:: javascript
 
-    // assets/js/greet.js
+    // assets/greet.js
     module.exports = function(name) {
         return `Yo yo ${name} - welcome to Encore!`;
     };
@@ -158,7 +158,7 @@ Great! Use ``require()`` to import ``jquery`` and ``greet.js``:
 
 .. code-block:: diff
 
-    // assets/js/app.js
+    // assets/app.js
     // ...
 
     + // loads the jquery package from node_modules
@@ -187,7 +187,7 @@ To export values using the alternate syntax, use ``export``:
 
 .. code-block:: diff
 
-    // assets/js/greet.js
+    // assets/greet.js
     - module.exports = function(name) {
     + export default function(name) {
         return `Yo yo ${name} - welcome to Encore!`;
@@ -197,7 +197,7 @@ To import values, use ``import``:
 
 .. code-block:: diff
 
-    // assets/js/app.js
+    // assets/app.js
     - require('../css/app.css');
     + import '../css/app.css';
 
@@ -219,12 +219,12 @@ etc.). To handle this, create a new "entry" JavaScript file for each page:
 
 .. code-block:: javascript
 
-    // assets/js/checkout.js
+    // assets/checkout.js
     // custom code for your checkout page
 
 .. code-block:: javascript
 
-    // assets/js/account.js
+    // assets/account.js
     // custom code for your account page
 
 Next, use ``addEntry()`` to tell Webpack to read these two new files when it builds:
@@ -234,9 +234,9 @@ Next, use ``addEntry()`` to tell Webpack to read these two new files when it bui
     // webpack.config.js
     Encore
         // ...
-        .addEntry('app', './assets/js/app.js')
-    +     .addEntry('checkout', './assets/js/checkout.js')
-    +     .addEntry('account', './assets/js/account.js')
+        .addEntry('app', './assets/app.js')
+    +     .addEntry('checkout', './assets/checkout.js')
+    +     .addEntry('account', './assets/account.js')
         // ...
 
 And because you just changed the ``webpack.config.js`` file, make sure to stop
@@ -285,7 +285,7 @@ file to ``app.scss`` and update the ``import`` statement:
 
 .. code-block:: diff
 
-    // assets/js/app.js
+    // assets/app.js
     - import '../css/app.css';
     + import '../css/app.scss';
 
@@ -336,7 +336,7 @@ If you want to only compile a CSS file, that's possible via ``addStyleEntry()``:
     Encore
         // ...
 
-        .addStyleEntry('some_page', './assets/css/some_page.css')
+        .addStyleEntry('some_page', './assets/styles/some_page.css')
     ;
 
 This will output a new ``some_page.css``.

frontend/encore/split-chunks.rst

@@ -14,10 +14,10 @@ To enable this, call ``splitEntryChunks()``:
         // ...
 
         // multiple entry files, which probably import the same code
-        .addEntry('app', './assets/js/app.js')
-        .addEntry('homepage', './assets/js/homepage.js')
-        .addEntry('blog', './assets/js/blog.js')
-        .addEntry('store', './assets/js/store.js')
+        .addEntry('app', './assets/app.js')
+        .addEntry('homepage', './assets/homepage.js')
+        .addEntry('blog', './assets/blog.js')
+        .addEntry('store', './assets/store.js')
 
     +     .splitEntryChunks()
 

mailer.rst

@@ -626,7 +626,7 @@ called ``css`` that points to the directory where ``email.css`` lives:
 
             paths:
                 # point this wherever your css files live
-                '%kernel.project_dir%/assets/css': css
+                '%kernel.project_dir%/assets/styles': styles
 
     .. code-block:: xml
 
@@ -642,7 +642,7 @@ called ``css`` that points to the directory where ``email.css`` lives:
                 <!-- ... -->
 
                 <!-- point this wherever your css files live -->
-                <twig:path namespace="css">%kernel.project_dir%/assets/css</twig:path>
+                <twig:path namespace="styles">%kernel.project_dir%/assets/styles</twig:path>
             </twig:config>
         </container>
 
@@ -653,7 +653,7 @@ called ``css`` that points to the directory where ``email.css`` lives:
             // ...
             'paths' => [
                 // point this wherever your css files live
-                '%kernel.project_dir%/assets/css' => 'css',
+                '%kernel.project_dir%/assets/styles' => 'styles',
             ],
         ]);
 
@@ -741,7 +741,7 @@ You can combine all filters to create complex email messages:
 
 This makes use of the :ref:`css Twig namespace <mailer-css-namespace>` we created
 earlier. You could, for example, `download the foundation-emails.css file`_
-directly from GitHub and save it in ``assets/css``.
+directly from GitHub and save it in ``assets/styles``.
 
 Signing and Encrypting Messages
 -------------------------------