Merge pull request #65 from weaverryan/readme-updates

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 the 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,116 @@
+Using Bootstrap CSS & JS
+========================
+
+Want to use Bootstrap (or something similar) in your project? No problem!
+First, install it. To be able to customize things further, we'll install
+``bootstrap-sass``:
+
+.. code-block:: terminal
+
+    $ yarn add bootstrap-sass --dev
+
+Importing Bootstrap SASS
+------------------------
+
+Now that ``bootstrap-sass`` lives in your ``node_modules`` directory, you can
+import it from any SASS or JavaScript file. For example, if you're already have
+a ``global.scss`` file, import it from there:
+
+.. code-block:: css
+
+    // assets/css/global.scss
+
+    // customize some Bootstrap variables
+    $brand-primary:         darken(#428bca, 20%);
+
+    // the ~ allows you to reference things in node_modules
+    @import '~bootstrap-sass/assets/stylesheets/bootstrap';
+
+That's it! This imports the ``node_modules/bootstrap-sass/assets/stylesheets/_bootstrap.scss``
+file into ``global.scss``. You can even customize the Bootstrap variables first!
+
+.. tip::
+
+    If you don't need *all* of Bootstrap's features, you can include specific files
+    in the ``bootstrap`` directory instead - e.g. ``~bootstrap-sass/assets/stylesheets/bootstrap/alerts``.
+
+After including ``bootstrap-sass``, your webpack builds might become slow. To fix
+this, you can use the ``resolve_url_loader`` option:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+    +     enableSassLoader({
+    +         'resolve_url_loader' => false
+    +     })
+    ;
+
+This disables the ``resolve-url-loader`` in Webpack, which means that any
+``url()`` paths in your SASS files must now be relative to the original source
+entry file instead of whatever file you're inside of (see `Problems with url()`_).
+To load Bootstrap, you'll need to override the path to its icons:
+
+.. code-block:: diff
+
+    // assets/css/global.scss
+
+    + $icon-font-path: "~bootstrap-sass/assets/fonts/bootstrap/";
+
+    + // set if you're also including font-awesome
+    + // $fa-font-path: "~font-awesome/fonts";
+
+    @import '~bootstrap-sass/assets/stylesheets/bootstrap';
+
+Importing Bootstrap JavaScript
+------------------------------
+
+Bootstrap JavaScript requires jQuery, so make sure you have this installed:
+
+.. code-block:: terminal
+
+    $ yarn add jquery --dev
+
+Next, make sure call ``.autoProvidejQuery()`` in your ``webpack.config.js`` file:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+        // ...
+    +     .autoProvidejQuery()
+
+This is needed because Bootstrap expects jQuery to be available as a global
+variable. Now, require bootstrap from any of your JavaScript files:
+
+.. code-block:: javascript
+
+    // main.js
+
+    var $ = require('jquery');
+    // JS is equivalent to the normal "bootstrap" package
+    // no need to set this to a variable, just require it
+    require('bootstrap-sass');
+
+    // or you can include specific pieces
+    // require('bootstrap-sass/javascripts/bootstrap/tooltip');
+    // require('bootstrap-sass/javascripts/bootstrap/popover');
+
+    $(document).ready(function() {
+        $('[data-toggle="popover"]').popover();
+    });
+
+Thanks to ``autoProvidejQuery()``, you can require any other jQuery
+plugins in a similar way:
+
+.. code-block:: javascript
+
+    // ...
+
+    // require the JavaScript
+    require('bootstrap-star-rating');
+    // require 2 CSS files needed
+    require('bootstrap-star-rating/css/star-rating.css');
+    require('bootstrap-star-rating/themes/krajee-svg/theme.css');
+
+.. _`Problems with url()`: https://github.com/webpack-contrib/sass-loader#problems-with-url

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`` paths are
+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
+
+    {# Your script/link tags don't need to change at all to support 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,31 @@
+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
+
+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.
+
+You can also pass options to the ``dev-server`` command: any options that
+are supported by the normal `webpack-dev-server`_. For example:
+
+.. code-block:: terminal
+
+    $ ./node_modules/.bin/encore dev-server --https --port 9000
+
+This will start a server at ``https://localhost:9000``.
+
+.. note::
+
+    Hot module replacement is not currently supported.
+
+.. _`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/