add migration guide

src/content/migrate/3.md

@@ -1,6 +1,6 @@
 ---
-title: To webpack v2, v3
-sort: 1
+title: To v2 or v3 from v1
+sort: 2
 contributors:
   - sokra
   - jhnns

src/content/migrate/4.md

@@ -0,0 +1,158 @@
+---
+title: To v4 from v3
+sort: 1
+contributors:
+  - sokra
+  - EugeneHlushko
+---
+
+This guide only shows major changes that affect end users. For more details please see [the changelog](https://github.com/webpack/webpack/releases).
+
+
+## Node.js v4
+
+If you are still using Node.js v4 or lower, you need to upgrade your Node.js installation to Node.js v6 or higher.
+
+
+## CLI
+
+The CLI has moved to a separate package: webpack-cli. You need to install it before using webpack, see [basic setup](/guides/getting-started/#basic-setup).
+
+
+## Update plugins
+
+Many 3rd-party plugins need to be upgraded to their latest version to be compatible.
+
+
+## mode
+
+Add the new [`mode`](/concepts/mode/) option to your config. Set it to production or development in your configuration depending on config type.
+
+__webpack.config.js__
+
+``` diff
+module.exports = {
+  // ...
+  mode: 'production',
+}
+```
+
+Alternatively you can pass it via CLI: `--mode production`/`--mode development`
+
+## Deprecated/Removed plugins
+
+These plugins can be removed from configuration as they are default in production mode:
+
+__webpack.config.js__
+
+``` diff
+module.exports = {
+  // ...
+  plugins: [
+-    new NoEmitOnErrorsPlugin(),
+-    new ModuleConcatenationPlugin(),
+-    new DefinePlugin({ "process.env.NODE_ENV": JSON.stringify("production") })
+-    new UglifyJsPlugin()
+  ],
+}
+```
+
+These plugins are default in development mode
+
+__webpack.config.js__
+
+``` diff
+module.exports = {
+  // ...
+  plugins: [
+-    new NamedModulesPlugin()
+  ],
+}
+```
+
+These plugins were deprecated and are now removed:
+
+__webpack.config.js__
+
+``` diff
+module.exports = {
+  // ...
+  plugins: [
+-    new NoErrorsPlugin(),
+-    new NewWatchingPlugin()
+  ],
+}
+```
+
+
+## CommonsChunkPlugin
+
+The `CommonsChunkPlugin` was removed. Instead the [`optimization.splitChunks`](/configuration/optimization/#optimization-splitchunks/) options can be used.
+
+See documentation of the [`optimization.splitChunks`](/configuration/optimization/#optimization-splitchunks/) for more details. The default configuration may already suit your needs.
+
+T> When generating the HTML from the stats you can use `optimization.splitChunks.chunks: "all"` which is the optimal configuration in most cases.
+
+## import() and CommonJS
+
+When using `import()` to load non-ESM the result has changed in webpack 4. Now you need to access the `default` property to get the value of `module.exports`.
+
+__non-esm.js__
+
+``` javascript
+module.exports = {
+  sayHello: () => {
+    console.log('hello world');
+  }
+};
+```
+
+__example.js__
+
+``` javascript
+function sayHello() {
+  import('./non-esm.js').then(module => {
+    module.default.sayHello();
+  });
+}
+```
+
+## json and loaders
+
+When using a custom loader to transform `.json` files you now need to change the module `type`:
+
+__webpack.config.js__
+
+``` diff
+module.exports = {
+  // ...
+  rules: [
+    {
+      test: /config\.json$/,
+      loader: 'special-loader',
++     type: 'javascript/auto',
+      options: {...}
+    }
+  ]
+};
+```
+
+When still using the `json-loader`, it can be removed:
+
+__webpack.config.js__
+
+``` diff
+module.exports = {
+  // ...
+  rules: [
+    {
+-     test: /\.json$/,
+-     loader: 'json-loader'
+    }
+  ]
+};
+```
+
+## module.loaders
+
+`module.loaders` were deprecated since webpack 2 and are now removed in favor of [`module.rules`](/configuration/module/#rule).