WIP - re-organizing and updating the docs

Author: weaverryan

README.rst

@@ -0,0 +1,30 @@
+Configuring Babel
+=================
+
+`Babel`_ is automatically configured for all ``.js`` and ``.jsx`` files via the
+``babel-loader`` with sensible defaults (e.g. with the ``env`` preset and
+``react`` if requested).
+
+Need to extend the Babel configuration further? The easiest way is via
+``configureBabel()``:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+    // ...
+
+    Encore
+        // ...
+
+        // modify our default Babel configuration
+        .configureBabel(function(babelConfig) {
+            babelConfig.presets.push('es2017');
+        })
+    ;
+
+You can also create a standard ``.babelrc`` file at the root of your project.
+Just make sure to configure it with all the presets you need: as soon as a
+``.babelrc`` is present, Encore can no longer add *any* Babel configuration for
+you!
+
+.. _`Babel`: http://babeljs.io/

docs/babel.rst

@@ -0,0 +1,19 @@
+Using Bootstrap CSS & JS
+========================
+
+TODO - show how to bring in bootstrap JS and bootstrap-sass.
+
+Here is an example from before to include... because I think it's really nice :).
+
+    // when no file path is defined (i.e. no file extension) Webpack loads the
+    // given JavaScript module installed in node_modules/ dir (Webpack knows all
+    // the specific files that must be loaded and in which order)
+    require('bootstrap-star-rating');
+
+    // when a file path is given, but it doesn't start with '/' or './', the file
+    // path is considered relative to node_modules/ dir
+    require('bootstrap-star-rating/css/star-rating.css');
+
+    // when a file path is given and it starts with '/', './', or '../', it's considered
+    // as the full file path for the asset (it can live outside the node_modules/ dir)
+    require('../../../../../node_modules/bootstrap-star-rating/themes/krajee-svg/theme.css');

docs/bootstrap.rst

@@ -0,0 +1,47 @@
+Using a CDN
+===========
+
+Are you deploying to a CDN? That's awesome :) - and configuring
+Encore for that is easy. Once you've made sure that your built files
+are uploaded to the CDN, configure it in Encore:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    // ...
+
+    Encore
+        .setOutputPath('web/build/')
+        // in dev mode, don't use the CDN
+        .setPublicPath('/build');
+        // ...
+    ;
+
+    + if (Encore.isProduction()) {
+    +     Encore.setPublicPath('https://my-cool-app.com.global.prod.fastly.net');
+    +
+    +     // guarantee that the keys in manifest.json are *still*
+    +     // prefixed with build/
+    +     // (e.g. "build/dashboard.js": "https://my-cool-app.com.global.prod.fastly.net/dashboard.js")
+    +     Encore.setManifestKeyPrefix('build/');
+    + }
+
+That's it! Internally, Webpack will now know to load assets from your CDN -
+e.g. ``https://my-cool-app.com.global.prod.fastly.net/dashboard.js``.
+
+.. note::
+
+    It's still your responsibility to put your assets on the CDN - e.g. by
+    uploading them or by using "origin pull", where your CDN pulls assets
+    directly from your web server.
+
+You *do* need to make sure that the ``script`` and ``link`` tags you include on your
+pages also uses the CDN. Fortunately, the ``manifest.json`` is automatically
+updated to point to the CDN. In Symfony, as long as you've configured
+:doc:`Asset Versioning </versioning>`_, you're done! The ``manifest.json``
+file includes the full CDN URL:
+
+.. code-block:: js
+
+    {# Same code you had before and setting up the CDN #}
+    <script src="{{ asset('build/dashboard.js') }}"></script>

docs/cdn.rst

@@ -0,0 +1,49 @@
+CSS Preprocessors: SASS, LESS, etc
+==================================
+
+Using Sass
+----------
+
+To use the Sass pre-processor, install the dependencies:
+
+.. code-block:: terminal
+
+    yarn add --dev sass-loader node-sass
+
+And enable it in ``webpack.config.js``:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+    // ...
+
+    Encore
+        // ...
+        .enableSassLoader()
+    ;
+
+That's it! All files ending in ``.sass`` or ``.scss`` will
+be processed.
+
+Using LESS
+----------
+
+To use the LESS pre-processor, install the dependencies:
+
+.. code-block:: terminal
+
+    yarn add --dev less-loader less
+
+And enable it in ``webpack.config.js``:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+    // ...
+
+    Encore
+        // ...
+        .enableLessLoader()
+    ;
+
+That's it! All files ending in ``.less`` will be pre-processed.

docs/css-preprocessors.rst

@@ -0,0 +1,22 @@
+Using webpack-dev-server and HMR
+================================
+
+While developing, instead of using ``encore dev --watch``, you can
+instead use the `webpack-dev-server`_:
+
+.. code-block:: terminal
+
+    ./node_modules/.bin/encore dev-server
+
+.. note::
+
+    Hot module replacement is not currently supported.
+
+This serves the built assets from a new server at ``http://localhost:8080``
+(it does not actually write any files to disk). This means your
+``script`` and ``link`` tags need to change to point to this.
+
+If you've activated the :ref:`manifest.json versioning <load-manifest-files>`
+you're done: the paths in your templates will automatically point to the dev server.
+
+.. _`webpack-dev-server`: https://webpack.js.org/configuration/dev-server/

docs/dev-server.rst

@@ -0,0 +1,63 @@
+Webpack Encore
+==============
+
+`Webpack Encore`_ is a simpler way to integrate `Webpack`_ into your
+application. It *wraps* Webpack, giving you a clean & powerful API
+for bundling JavaScript modules, pre-processing CSS & JS and compiling
+and minifying assets. Encore gives you professional asset system
+that's a *delight* to use.
+
+Encore is inspired by `Webpacker`_ and `Mix`_, but stays in the spirit of
+Webpack: using its features, concepts and naming conventions for a familiar
+feel. It aims to solve the most common Webpack use cases.
+
+.. tip::
+
+    Encore is made by `Symfony`_ and works *beautifully* in Symfony applications.
+    But it can easily be used in any application... in any language!
+
+Documentation
+-------------
+
+Getting Started
+...............
+
+* :doc:`Installation </installation>`
+* :doc:`First Example </simple-example>`
+
+Adding more Features
+....................
+
+* :doc:`CSS Preprocessors: SASS, LESS, etc </css-preprocessors>`
+* :doc:`PostCSS and autoprefixing </postcss>`
+* :doc:`Enabling React.js </reactjs>`
+* :doc:`Configuring Babel </babel>`
+* :doc:`Sourcemaps </sourcemaps>`
+
+Optimizing
+..........
+
+* :doc:`Versioning and manifest.json </versioning>`
+* :doc:`Using A CDN </cdn>`
+* :doc:`Creating a "Shared" entry for re-used modules </shared-entry>`
+
+Guides
+......
+
+* :doc:`Using Bootstrap CSS & JS </bootstrap>`
+* :doc:`Creating Page-Specific CSS/JS </page-specific-assets>`
+* :doc:`jQuery and Legacy Applications </legacy-apps>`
+* :doc:`Passing Information from Twig to JavaScript </server-data>`
+* :doc:`webpack-dev-server and Hot Module Replacement (HMR) </dev-server>`
+
+Full API
+........
+
+* `Full API`_: https://github.com/symfony/webpack-encore/blob/master/index.js
+
+.. _`Webpack Encore`: https://www.npmjs.com/package/@symfony/webpack-encore
+.. _`Webpack`: https://webpack.js.org/
+.. _`Webpacker`: https://github.com/rails/webpacker
+.. _`Mix`: https://laravel.com/docs/5.4/mix
+.. _`Symfony`: http://symfony.com/
+.. _`Full API`: https://github.com/symfony/webpack-encore/blob/master/index.js

docs/index.rst

@@ -0,0 +1,32 @@
+Installation
+============
+
+First, make sure you `install Node.js`_ and also the `yarn package manager`_.
+
+Then, install Encore into your project with yarn:
+
+.. code-block:: terminal
+
+    $ yarn add @symfony/webpack-encore --dev
+
+.. note::
+
+    If you want to use `npm`_ instead of `yarn`_, replace ``yarn add xxx --dev`` by
+    ``npm install xxx --save-dev``.
+
+This command creates (or modifies) a ``package.json`` file and downloads
+dependencies into a ``node_modules`` directory. When using Yarn, a file called
+``yarn.lock`` is also created/updated. When using npm 5, a ``package-lock.json``
+file is created/updated.
+
+.. tip::
+
+    You should commit ``package.json`` and ``yarn.lock`` (or ``package-lock.json``
+    if using npm) to version control, but ignore ``node_modules``.
+
+Next, create your ``webpack.config.js`` in :doc:`/simple-example`!
+
+.. _`install Node.js`: https://nodejs.org/en/download/
+.. _`yarn package manager`: https://yarnpkg.com/lang/en/docs/install/
+.. _`npm`: https://www.npmjs.com/
+.. _`yarn`: https://yarnpkg.com/

docs/installation.rst

@@ -0,0 +1,53 @@
+jQuery and Legacy Applications
+==============================
+
+Some legacy JavaScript applications use programming practices that don't play
+well with the new practices promoted by Webpack. The most common of these
+problems is using code (e.g. jQuery plugins) that assume that jQuery is already
+available via the the ``$`` or ``jQuery`` global variables. If those variables
+are not defined, you'll get these errors:
+
+.. code-block:: text
+
+    Uncaught ReferenceError: $ is not defined at [...]
+    Uncaught ReferenceError: jQuery is not defined at [...]
+
+Instead of rewriting everything, Encore allows for a different solution. Thanks
+to the ``autoProvidejQuery()`` method, whenever a JavaScript file uses the ``$``
+or ``jQuery`` variables, Webpack automatically requires ``jquery`` and creates
+those variables for you.
+
+So, when working with legacy applications, you may need to add the following to
+``webpack.config.js``:
+
+.. code-block:: diff
+
+    Encore
+        // ...
+    +     .autoProvidejQuery()
+    ;
+
+Internally, this ``autoProvidejQuery()`` method uses the ``autoProvideVariables()``
+method from Encore. In practice, it's equivalent to doing:
+
+.. code-block:: javascript
+
+    Encore
+        // you can use this method to provide other common global variables,
+        // such as '_' for the 'underscore' library
+        .autoProvideVariables({
+            $: 'jquery',
+            jQuery: 'jquery'
+        })
+        // ...
+    ;
+
+If you also need to provide access to ``$`` and ``jQuery`` variables outside of
+JavaScript files processed by Webpack, you must create the global variables
+yourself in some file loaded before the legacy JavaScript code. For example, you
+can define a ``common.js`` file processed by Webpack and loaded in every page
+with the following content:
+
+.. code-block:: javascript
+
+    window.$ = window.jQuery = require('jquery');

docs/legacy-apps.rst

@@ -0,0 +1,4 @@
+Creating Page-Specific CSS/JS
+=============================
+
+TODO