Documenting copyFiles() and a few small things

Author: weaverryan

frontend.rst

@@ -48,6 +48,7 @@ Adding more Features
 * :doc:`PostCSS and autoprefixing </frontend/encore/postcss>`
 * :doc:`Enabling React.js </frontend/encore/reactjs>`
 * :doc:`Enabling Vue.js (vue-loader) </frontend/encore/vuejs>`
+* :doc:`/frontend/encore/copy-files`
 * :doc:`Configuring Babel </frontend/encore/babel>`
 * :doc:`Source maps </frontend/encore/sourcemaps>`
 * :doc:`Enabling TypeScript (ts-loader) </frontend/encore/typescript>`

frontend/encore/copy-files.rst

@@ -0,0 +1,66 @@
+Copying & Referencing Images
+============================
+
+Need to reference a static file - like the path to an image for an ``img`` tag?
+That can be tricky if you store your assets outside of the public document root.
+Fortunately, depending on your situation, there is a solution!
+
+Referencing Images from Inside a Webpacked JavaScript File
+----------------------------------------------------------
+
+To reference an image tag from inside a JavaScript file, *require* the file:
+
+.. code-block:: javascript
+
+    // assets/js/app.js
+
+    // returns the final, public path to this file
+    // path is relative to this file - e.g. assets/images/logo.png
+    const logoPath = require('../images/logo.png');
+
+    var html = `<img src="${logoPath}">`;
+
+When you ``require`` (or ``import``) an image file, Webpack copies it into your
+output directory and returns the final, *public* path to that file.
+
+Referencing Image files from a Template
+---------------------------------------
+
+To reference an image file from outside of a JavaScript file that's processed by
+Webpack - like a template - you can use the ``copyFiles()`` method to copy those
+files into your final output directory.
+
+.. code-block:: diff
+
+    // webpack.config.js
+
+    Encore
+        // ...
+        .setOutputPath('web/build/')
+
+    +     .copyFiles({
+    +         from: './assets/images',
+    + 
+    +         // optional target path, relative to the output dir
+    +         //to: 'images/[path][name].[ext]',
+    +
+    +         // only copy files matching this pattern
+    +         //pattern: /\.(png|jpg|jpeg)$/
+    +     })
+
+This will copy all files from ``assets/images`` into ``web/build`` (the output
+path). If you have :doc:`versioning enabled <versioning>`, the copied files will
+include a hash based on their content.
+
+To render inside Twig, use the ``asset()`` function:
+
+    {# assets/images/logo.png was copied to web/build/logo.png #}
+    <img src="{{ asset('build/logo.png') }}"
+
+    {# assets/images/subdir/logo.png was copied to web/build/subdir/logo.png #}
+    <img src="{{ asset('build/subdir/logo.png') }}"
+
+Make sure you've enabled the :ref:`json_manifest_path <load-manifest-files>` option,
+which tells the ``asset()`` function to read the final paths from the ``manifest.json``
+file. If you're not sure what path argument to pass to the ``asset()`` function,
+find the file in ``manifest.json`` and use the *key* as the argument.

frontend/encore/faq.rst

@@ -129,4 +129,11 @@ this via:
     // require a non-minified file whenever possible
     require('respond.js/dest/respond.src.js');
 
+I need to execute Babel on a third-party Module
+-----------------------------------------------
+
+For performance, Encore does not process libraries inside ``node_modules/`` through
+Babel. But, you can change that via the ``configureBabel()`` method. See
+:doc:`/frontend/encore/babel` for details.
+
 .. _`rsync`: https://rsync.samba.org/

frontend/encore/simple-example.rst

@@ -316,7 +316,32 @@ you need a feature, Encore will tell you what you need to install. Run:
 Your app now supports Sass. Encore also supports LESS and Stylus. See
 :doc:`/frontend/encore/css-preprocessors`.
 
+Compiling Only a CSS File
+-------------------------
+
+.. caution::
+
+    Using ``addStyleEntry()`` is supported, but not recommended. A better option
+    is to use follow the pattern above: use ``addEntry()`` to point to a JavaScript
+    file, then require the CSS needed from inside of that.
+
+If you want to only compile a CSS file, that's possible via ``addStyleEntry()``:
+
+.. code-block:: javascript
+
+    // webpack/config.js
+    Encore
+        // ...
+
+        .addStyleEntry('some_page', './assets/css/some_page.css')
+    ;
+
+This will output a new ``some_page.css``.
+
 Keep Going!
 -----------
 
-Go back to the :ref:`List of Encore Articles <encore-toc>` to learn more and add new features.
+Encore support many more features! For a full list of what you can do, see
+`Encore's index.js file`_. Or, go back to :ref:`list of Encore articles <encore-toc>`.
+
+.. _`Encore's index.js file`: https://github.com/symfony/webpack-encore/blob/master/index.js