Merge pull request #271 from kalcifer/feat/code-splitting

How to split code?

Closes #3.

Author: bebraw

content/how-to/code-splitting/splitting-css.md

@@ -0,0 +1,86 @@
+---
+title: How to Split CSS?
+contributors:
+  - pksjce
+---
+
+In webpack, when you use the css-loader and import CSS into your JavaScript files, the CSS is bundled along with your Javascript.
+This has the disadvantage that, you will not be able to utilize the browser's ability to load CSS asynchronously and parallel. Instead, your page will have to wait until your whole JavaScript bundle is loaded, to style itself.
+webpack can help with this problem by bundling the CSS separately using [extract-text-webpack-plugin](https://github.com/webpack/extract-text-webpack-plugin) and the [css-loader](https://github.com/webpack/css-loader).
+
+## Using `css-loader`
+
+To import css into your JavaScript code like [any other module](concept/modules), you will have to use the [css-loader](https://github.com/webpack/css-loader)
+The webpack config with `css-loader` will look like
+
+```javascript
+//webpack.config.js
+
+modules.exports = function(env){
+    entry: '..',
+    ...
+    module: {
+        loaders: [{
+            test: /\.css$/,
+            exclude: /node_modules/,
+            loader: 'css-loader'
+        }]
+    }
+    ...
+}
+```
+
+## Using `extract-text-webpack-plugin` - ExtractTextPlugin
+
+Install this plugin as follows
+```
+npm i --save-dev extract-text-webpack-plugin
+```
+
+To use this `ExtractTextPlugin`, it needs to be added to the `webpack.config.js` file in two steps.
+### In the loader
+
+Adapting from the previous example with the `css-loader`, we should add `ExtractTextPlugin` as follows
+
+```javascript
+...
+loader: ExtractTextPlugin.extract('css-loader?sourceMap') //Can be used without sourcemaps too.
+...
+```
+
+### In the plugin
+
+```javascript
+new ExtractTextPlugin({ filename: 'bundle.css', disable: false, allChunks: true })
+```
+
+With above two steps, you can generate a new bundle specifically for all the CSS modules and add them as a separate tag in the `index.html`
+For more info on how to use the api please go to [`ExtractTextPlugin` api](https://github.com/webpack/extract-text-webpack-plugin#api).
+
+The full config for splitting css with `ExtractTextPlugin` is as follows
+
+```javascript
+var ExtractTextPlugin = require('extract-text-webpack-plugin');
+module.exports = function () {
+    return {
+        entry: './main.js',
+        output: {
+            path: './dist',
+            filename: 'bundle.js'
+        },
+        module: {
+            loaders: [{
+                test: /\.css$/,
+                exclude: /node_modules/,
+                loader: Extract.extract({
+                    loader: 'css-loader?sourceMap'
+                })
+            }]
+        },
+        devtool: 'source-map',
+        plugins: [
+            new ExtractTextPlugin({ filename: 'bundle.css', disable: false, allChunks: true })
+        ]
+    }
+}
+```

content/how-to/code-splitting/splitting-require.md

@@ -0,0 +1,97 @@
+---
+title: How to Split Using require.ensure()?
+contributors:
+  - pksjce
+---
+
+In this section, we will discuss how webpack splits code using `require.ensure()`.
+
+## `require.ensure()`
+
+webpack statically parses for `require.ensure()` in the code while building and adds the modules here into a separate chunk. This new chunk is loaded on demand by webpack through jsonp.
+
+The syntax is as follows
+
+```javascript
+require.ensure(dependencies: String[], callback: function(require), chunkName: String)
+```
+
+#### dependencies
+This is an array of strings where we can declare all the modules that need to be made available before all the code in the callback function can be executed.
+
+#### callback
+This is the callback function that webpack will execute once the dependencies are loaded. An implementation of the require object is sent as a parameter to this function. This is so that, we can further `require()` the dependencies and any other modules for execution.
+
+#### chunkName
+The chunkName is the name given to the chunk created by this particular `require.ensure()`. By giving the same name at various different split points of `require.ensure()`, we can make sure all the dependencies are collectively put in the same bundle.
+
+Let us consider the following project
+
+```bash
+\\ file structure
+    |
+    js --|
+    |    |-- entry.js
+    |    |-- a.js
+    |    |-- b.js
+    webpack.config.js
+    |
+    dist 
+```
+
+```javascript
+\\ entry.js
+
+require('a')
+require.ensure([], function(require){
+    require('b')
+})
+
+\\ a.js
+console.log('***** I AM a *****')
+
+\\ b.js
+console.log('***** I AM b *****')
+```
+
+```javascript
+\\ webpack.config.js
+
+module.exports = function(env) {
+    return {
+        entry: './js/entry.js',
+        output: {
+            filename: 'bundle.js',
+            path: './dist'
+        }
+    }
+}
+```
+On running webpack on this project, we find that webpack has created two new bundles, `bundle.js` and `0.bundle.js`.
+
+`entry.js` and `a.js` are bundled in `bundle.js`.
+
+`b.js` is bundled in `0.bundle.js`.
+
+## Gotchas for `require.ensure()`
+
+### Empty Array as Parameter
+
+```javascript
+require.ensure([], function(require){
+    require('./a.js')
+})
+```
+
+The above code ensures that a split point is created and `a.js` is bundled separately by webpack.
+
+### Dependencies as Parameter
+
+```javascript
+require.ensure(['./a.js'], function(require) {
+    require('./b.js');
+})
+```
+
+In the above code, `a.js` and `b.js` are bundled together and split from the main bundle. But only the contents of `b.js` are executed. The contents of `a.js` are only made available and not executed.
+To execute `a.js`, we will have to require it in a sync manner like `require('./a.js')` for the JavaScript to get executed.

content/how-to/code-splitting/splitting-vendor.md

@@ -0,0 +1,140 @@
+---
+title: How to Split Vendor Files?
+contributors:
+  - pksjce
+---
+
+A typical application uses third party libraries for framework/functionality needs. Particular versions of these libraries are used and code here does not change often. However, the application code changes frequently.
+
+Bundling application code with third party code would be inefficient. This is because the browser can cache asset files based on the cache header and files can be cached without needing to call the cdn again if it's contents don't change. To take advantage of this, we want to keep the hash of the vendor files constant regardless of application code changes.
+
+We can do this only when we separate the bundles for vendor and application code.
+
+Let's consider a sample application, that uses [momentjs](https://www.npmjs.com/package/moment) which is a time formatting library commonly used.
+
+Install `moment` as follows in your application directory.
+
+`npm install --save moment`
+
+The index file will require `moment` as a dependency and log the current date as follows
+
+__index.js__
+```javascript
+
+var moment = require('moment');
+console.log(moment().format())
+
+```
+
+We can bundle the application with webpack using the following config
+
+__webpack.config.js__
+
+```javascript
+
+modules.export = function(env) {
+    return {
+        entry: './index.js',
+        output: {
+            filename: '[chunkhash].[name].js`,
+            path: './dist'
+        }
+    }
+}
+```
+
+On running `webpack` in your application, if you inspect the resulting bundle, you will see that `moment` and `index.js` have been bundled in `bundle.js`.
+
+This is not ideal for the application. If the code in `index.js` changes, then the whole bundle is rebuilt. The browser will have to load a new copy of the new bundle even though most of it hasn't changed at all.
+
+## Multiple Entries
+
+Let's try to mitigate this by adding a separate entry point for `moment` and name it `vendor`
+
+__webpack.config.js__
+
+```javascript
+
+modules.export = function(env) {
+    return {
+        entry: {
+            main: './index.js',
+            vendor: 'moment'
+        },
+        output: {
+            filename: '[chunkhash].[name].js`,
+            path: './dist'
+        }
+    }
+}
+```
+
+On running `webpack` now, we see that two bundles have been created. If you inspect these though, you will find that the code for `moment` is present in both the files!
+
+It is for this reason, that we will need to use the [CommonsChunkPlugin](/configuration/plugins).
+
+## `CommonsChunkPlugin`
+
+This is a pretty complex plugin. It fundamentally allows us to extract all the common modules from different bundles and add them to the common bundle. If a common bundle does not exist, then it creates a new one.
+
+We can modify our webpack config file to use the `CommonsChunkPlugin` as follows
+
+__webpack.config.js__
+
+```javascript
+
+var webpack = require('webpack');
+modules.export = function(env) {
+    return {
+        entry: {
+            main: './index.js',
+            vendor: 'moment'
+        },
+        output: {
+            filename: '[chunkhash].[name].js`,
+            path: './dist'
+        },
+        plugins: [
+            new webpack.optimize.CommonsChunkPlugin({
+                name: 'vendor' // Specify the common bundle's name.
+            })
+        ]
+    }
+}
+```
+Now run `webpack` on your application. Bundle inspection shows that `moment` code is present only in the vendor bundle.
+
+## Manifest File
+
+But, if we change application code and run `webpack` again, we see that the hash for the vendor file changes. Even though we achieved separate bundles for `vendor` and `main` bundles, we see that the `vendor` bundle changes when the application code changes.
+This means that we still don't reap the benefits of browser caching because the hash for vendor file changes on every build and the browser will have to reload the file.
+
+The issue here is that on every build, webpack generates some webpack runtime code, which helps webpack do it's job. When there is a single bundle, the runtime code resides in it. But when multiple bundles are generated, the runtime code is extracted into the common module, here the `vendor` file.
+
+To prevent this, we need extract out the runtime into a separate manifest file. Even though we are creating another bundle, the overhead is offset by the long term caching benefits that we obtain on the `vendor` file.
+
+__webpack.config.js__
+
+```javascript
+
+var webpack = require('webpack');
+modules.export = function(env) {
+    return {
+        entry: {
+            main: './index.js',
+            vendor: 'moment'
+        },
+        output: {
+            filename: '[chunkhash].[name].js`,
+            path: './dist'
+        },
+        plugins: [
+            new webpack.optimize.CommonsChunkPlugin({
+                names: ['vendor', 'manifest'] // Specify the common bundle's name.
+            })
+        ]
+    }
+}
+```
+
+With the above webpack config, we see three bundles being generated. `vendor`, `main` and `manifest` bundles.

content/how-to/split-code.md

@@ -1,11 +1,34 @@
 ---
 title: How to Split Code?
+contributors:
+  - pksjce
 ---
-> what is code splitting
-> System.import
-> dynamic System.import
-> require.ensure
-> AMD require
-
-> see also [[Output]]
-> see also [[dynamic dependencies]]
+
+Code splitting is the most compelling feature for  `webpack` usage. You can split your code into various bundles and load them on demand with`webpack`. It allows to tweak an application for these optimisations using the configuration.
+You can load them at a later time in your code or in a specific route only or on an event from the user even.
+
+There are mainly two kind of code-splits that need to be accomplished with `webpack`
+
+## On demand code-splitting
+
+`webpack` can help us split our code into logical pieces or chunks as per our application routes or as per predicted user behaviour. This means that we can load non-essential assets when the user performs an action like route change and demands for it.
+
+### Code splitting with `require.ensure()`
+
+`require.ensure()` is the CommonJS way of including assets asynchronously. By adding `require.ensure([<fileurl>])`, we can define a split point in the code. webpack can then create a separate bundle of all the code inside this split point.
+Learn [how to split your code using `require.ensure()`](/how-to/code-splitting/splitting-require)
+
+?> Document `System.import()`
+
+## Resource splitting for cacheing and parallel loads
+
+### CSS splitting
+
+An application owner would want to split all the css into a separate bundle. This enhances cacheability of the resource bundle and also allows the browser to parallely load the bundle which makes for a solid performance improvement.
+Learn [how to split your css using Extract-Text-Webpack-Plugin](/how-to/code-splitting/splitting-css)
+
+### Vendor code splitting
+
+A typical application uses third party libraries for framework/functionality needs. Particular versions of these libraries are used and code here does not change often. However, the application code changes frequently. Bundling application code with third party code would be inefficient. This is because the browser can cache asset files based on the cache header. To take advantage of this, we want to keep the hash of the vendor files constant regardless of application code changes. We can do this only when we separate the bundles for vendor and application code.
+
+Learn [how to split your vendor code using CommonsChunkPlugin](/how-to/code-splitting/splitting-vendor)