document pre/post loaders

Author: yyx990803

docs/en/configurations/advanced.md

@@ -1,57 +1,80 @@
 # Advanced Loader Configuration
 
-Sometimes you may want to apply a custom loader string to a language instead of letting `vue-loader` infer it. Or you may simply want to overwrite the built-in loader configuration for the default languages. To do that, add a `vue` block in your Webpack config file, and specify the `loaders` option.
+Sometimes the you may want to:
 
-### Webpack 1.x
+1. Apply a custom loader string to a language instead of letting `vue-loader` infer it;
+
+2. Overwrite the built-in loader configuration for the default languages;
+
+3. Pre-process or post-process a specific language block with custom loaders.
+
+To do that, specify the `loaders` option for `vue-loader`:
+
+> Note that `preLoaders` and `postLoaders` are only supported in >=10.3.0
+
+### Webpack 2.x
 
 ``` js
-// webpack.config.js
 module.exports = {
   // other options...
   module: {
-    loaders: [
+    // module.rules is the same as module.loaders in 1.x
+    rules: [
       {
         test: /\.vue$/,
-        loader: 'vue'
+        loader: 'vue-loader',
+        options: {
+          // `loaders` will overwrite the default loaders.
+          // The following config will cause all <script> tags without "lang"
+          // attribute to be loaded with coffee-loader
+          loaders: {
+            js: 'coffee-loader'
+          },
+
+          // `preLoaders` are attached before the default loaders.
+          // You can use this to pre-process language blocks - a common use
+          // case would be build-time i18n.
+          preLoaders: {
+            js: '/path/to/custom/loader'
+          },
+
+          // `postLoaders` are attached after the default loaders.
+          //
+          // - For `html`, the result returned by the default loader
+          //   will be compiled JavaScript render function code.
+          //
+          // - For `css`, the result will be returned by vue-style-loader
+          //   which isn't particularly useful in most cases. Using a postcss
+          //   plugin will be a better option.
+          postLoaders: {
+            html: 'babel-loader'
+          }
+        }
       }
     ]
-  },
-  // vue-loader configurations
-  vue: {
-    // ... other vue options
-    loaders: {
-      // load all <script> without "lang" attribute with coffee-loader
-      js: 'coffee-loader',
-      // allows you to write markdown inside <template> tags...
-      // (note this only works for 10.2.0+)
-      html: 'marked'
-    }
   }
 }
 ```
 
-### Webpack 2.x
+### Webpack 1.x
 
 ``` js
+// webpack.config.js
 module.exports = {
   // other options...
   module: {
-    // module.rules is the same as module.loaders in 1.x
-    rules: [
+    loaders: [
       {
         test: /\.vue$/,
-        loader: 'vue-loader',
-        options: {
-          loaders: {
-            // load all <script> without "lang" attribute with coffee-loader
-            js: 'coffee-loader',
-            // allows you to write markdown inside <template> tags...
-            // (note this only works for 10.2.0+)
-            html: 'marked'
-          }
-        }
+        loader: 'vue'
       }
     ]
+  },
+  // vue-loader configurations
+  vue: {
+    loaders: {
+      // same configuration rules as above
+    }
   }
 }
 ```

docs/en/configurations/extract-css.md

@@ -2,10 +2,10 @@
 
 Example config to extract all the processed CSS in all Vue components into a single CSS file:
 
-### Webpack 1.x
+### Webpack 2.x
 
 ``` bash
-npm install extract-text-webpack-plugin --save-dev
+npm install extract-text-webpack-plugin@2.x --save-dev
 ```
 
 ``` js
@@ -15,30 +15,31 @@ var ExtractTextPlugin = require("extract-text-webpack-plugin")
 module.exports = {
   // other options...
   module: {
-    loaders: [
+    rules: [
       {
         test: /\.vue$/,
-        loader: 'vue'
-      },
+        loader: 'vue-loader',
+        options: {
+          loaders: {
+            css: ExtractTextPlugin.extract({
+              loader: 'css-loader',
+              fallbackLoader: 'vue-style-loader' // <- this is a dep of vue-loader, so no need to explicitly install if using npm3
+            })
+          }
+        }
+      }
     ]
   },
-  vue: {
-    loaders: {
-      css: ExtractTextPlugin.extract("css"),
-      // you can also include <style lang="less"> or other langauges
-      less: ExtractTextPlugin.extract("css!less")
-    }
-  },
   plugins: [
     new ExtractTextPlugin("style.css")
   ]
 }
 ```
 
-### Webpack 2.x
+### Webpack 1.x
 
 ``` bash
-npm install extract-text-webpack-plugin@2.x --save-dev
+npm install extract-text-webpack-plugin --save-dev
 ```
 
 ``` js
@@ -48,21 +49,20 @@ var ExtractTextPlugin = require("extract-text-webpack-plugin")
 module.exports = {
   // other options...
   module: {
-    rules: [
+    loaders: [
       {
         test: /\.vue$/,
-        loader: 'vue-loader',
-        options: {
-          loaders: {
-            css: ExtractTextPlugin.extract({
-              loader: 'css-loader',
-              fallbackLoader: 'vue-style-loader' // <- this is a dep of vue-loader, so no need to explicitly install if using npm3
-            })
-          }
-        }
-      }
+        loader: 'vue'
+      },
     ]
   },
+  vue: {
+    loaders: {
+      css: ExtractTextPlugin.extract("css"),
+      // you can also include <style lang="less"> or other langauges
+      less: ExtractTextPlugin.extract("css!less")
+    }
+  },
   plugins: [
     new ExtractTextPlugin("style.css")
   ]

docs/en/options.md

@@ -2,18 +2,7 @@
 
 ## Usage Difference Between Webpack 1 & 2
 
-For Webpack 1.x: add a root `vue` block in your Webpack config:
-
-``` js
-module.exports = {
-  // ...
-  vue: {
-    // vue-loader options
-  }
-}
-```
-
-For Webpack 2 (^2.1.0-beta.25):
+For Webpack 2: pass the options directly to the loader rule.
 
 ``` js
 module.exports = {
@@ -32,11 +21,22 @@ module.exports = {
 }
 ```
 
+For Webpack 1.x: add a root `vue` block in your Webpack config.
+
+``` js
+module.exports = {
+  // ...
+  vue: {
+    // vue-loader options
+  }
+}
+```
+
 ### loaders
 
-- type: `Object`
+- type: `{ [lang: string]: string }`
 
-  An object specifying Webpack loaders to use for language blocks inside `*.vue` files. The key corresponds to the `lang` attribute for language blocks, if specified. The default `lang` for each type is:
+  An object specifying Webpack loaders to overwrite the default loaders used for language blocks inside `*.vue` files. The key corresponds to the `lang` attribute for language blocks, if specified. The default `lang` for each type is:
 
   - `<template>`: `html`
   - `<script>`: `js`
@@ -45,18 +45,43 @@ module.exports = {
   For example, to use `babel-loader` and `eslint-loader` to process all `<script>` blocks:
 
   ``` js
-  // ...
-  vue: {
-    loaders: {
-      js: 'babel!eslint'
-    }
+  // Webpack 2.x config
+  module: {
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader',
+        options: {
+          loaders: {
+            js: 'babel-loader!eslint-loader'
+          }
+        }
+      }
+    ]
   }
   ```
 
+### preLoaders
+
+- type: `{ [lang: string]: string }`
+- only supported in >=10.3.0
+
+  The config format is the same as `loaders`, but `preLoaders` are applied to corresponding language blocks before the default loaders. You can use this to pre-process language blocks - a common use case would be build-time i18n.
+
+### postLoaders
+
+- type: `{ [lang: string]: string }`
+- only supported in >=10.3.0
+
+  The config format is the same as `loaders`, but `postLoaders` are applied after the default loaders. You can use this to post-process language blocks. However note that this is a bit more complicated:
+
+  - For `html`, the result returned by the default loader will be compiled JavaScript render function code.
+
+  - For `css`, the result will be returned by `vue-style-loader` which isn't particularly useful in most cases. Using a postcss plugin will be a better option.
+
 ### postcss
 
 - type: `Array` or `Function` or `Object`
-- `Object` format only supported in ^8.5.0
 
   Specify custom PostCSS plugins to be applied to CSS inside `*.vue` files. If using a function, the function will called using the same loader context and should return an Array of plugins.