From 46935d345039d824ea5fd375d06824ab1e2380f5 Mon Sep 17 00:00:00 2001
From: Evan You <yyx990803@gmail.com>
Date: Tue, 24 Apr 2018 12:35:51 -0400
Subject: [PATCH] readme

---
 README.md | 304 +++++-------------------------------------------------
 1 file changed, 28 insertions(+), 276 deletions(-)

diff --git a/README.md b/README.md
index 1716c1310..98ffa1b99 100644
--- a/README.md
+++ b/README.md
@@ -1,290 +1,42 @@
-# vue-loader@next [![Build Status](https://circleci.com/gh/vuejs/vue-loader/tree/next.svg?style=shield)](https://circleci.com/gh/vuejs/vue-loader/tree/next) [![Windows Build status](https://ci.appveyor.com/api/projects/status/8cdonrkbg6m4k1tm/branch/next?svg=true)](https://ci.appveyor.com/project/yyx990803/vue-loader/branch/next)
+# vue-loader [![Build Status](https://circleci.com/gh/vuejs/vue-loader/tree/master.svg?style=shield)](https://circleci.com/gh/vuejs/vue-loader/tree/master) [![Windows Build status](https://ci.appveyor.com/api/projects/status/8cdonrkbg6m4k1tm/branch/master?svg=true)](https://ci.appveyor.com/project/yyx990803/vue-loader/branch/master)
 
-This is the WIP branch of the next version of `vue-loader`. It uses a fairly different new architecture that is able to apply whatever rules defined in the main webpack config to the language blocks inside a `*.vue` file.
+> webpack loader for Vue Single-File Components
 
-## Example Usage
+- [Documentation](https://vue-loader.vuejs.org)
+- [Migrating from v14](https://vue-loader.vuejs.org/migrating.html)
 
-``` js
-// webpack.config.js
-const path = require('path')
-const { VueLoaderPlugin } = require('vue-loader')
+## What is Vue Loader?
 
-module.exports = {
-  mode: 'development',
-  module: {
-    rules: [
-      {
-        test: /\.vue$/,
-        loader: 'vue-loader'
-      },
-      // this will apply to both plain .js files
-      // AND <script> blocks in vue files
-      {
-        test: /\.js$/,
-        loader: 'babel-loader'
-      },
-      // this will apply to both plain .css files
-      // AND <style> blocks in vue files
-      {
-        test: /\.css$/,
-        use: [
-          'vue-style-loader',
-          'css-loader'
-        ]
-      },
-      // this will apply to both plain .scss files
-      // AND <style lang="scss"> blocks in vue files
-      {
-        test: /\.scss$/,
-        use: [
-          'vue-style-loader',
-          'css-loader',
-          {
-            loader: 'sass-loader',
-            options: {
-              data: '$color: red;'
-            }
-          }
-        ]
-      }
-    ]
-  },
-  plugins: [
-    // make sure to include the plugin for the magic
-    new VueLoaderPlugin()
-  ]
-}
-```
-
-## Notable Breaking Changes
-
-### Loader Inference
-
-`vue-loader` 15 now infers loaders to use for language blocks a bit differently.
-
-Take `<style lang="less">` as an example: in v14 and below, it will attempt to load the block with `less-loader`, and implicitly chains `css-loader` and `vue-style-loader` after it, all using inline loader strings.
-
-In v15, `<style lang="less">` will behave as if it's an actual `*.less` file being loaded. So, in order to process it, you need to provide an explicit rule in your main webpack config:
-
-``` js
-{
-  module: {
-    rules: [
-      // ...other rules
-      {
-        test: /\.less$/,
-        use: [
-          'vue-style-loader',
-          'css-loader',
-          'less-loader'
-        ]
-      }
-    ]
-  }
-}
-```
-
-The benefit is that this same rule also applies to plain `*.less` imports from JavaScript, and you can configure options for these loaders anyway you want. In v14 and below, if you want to provide custom options to an inferred loader, you'd have to duplicate it under `vue-loader`'s own `loaders` option. In v15 it is no longer necessary.
-
-v15 also allows using non-serializable options for loaders, which was not possible in previous versions.
-
-### Template Preprocessing
-
-v14 and below uses [consolidate](https://github.com/tj/consolidate.js/) to compile `<template lang="xxx">`. v15 now applies preprocessing for them using webpack loaders instead.
-
-Note that some template loaders such as `pug-loader` exports a compiled templating function instead of plain HTML. In order to pass the correct content to Vue's template compiler, you must use a loader that outputs plain HTML instead. For example, to support `<template lang="pug">`, you can use [pug-plain-loader](https://github.com/yyx990803/pug-plain-loader):
-
-``` js
-{
-  module: {
-    rules: [
-      {
-        test: /\.pug$/,
-        loader: 'pug-plain-loader'
-      }
-    ]
-  }
-}
-```
-
-If you also intend to use it to import `.pug` files as HTML strings in JavaScript, you will need to chain `raw-loader` after the preprocessing loader. Note however adding `raw-loader` would break the usage in Vue components, so you need to have two rules, one of them targeting Vue files using a `resourceQuery`, the other one (fallback) targeting JavaScript imports:
-
-``` js
-{
-  module: {
-    rules: [
-      {
-        test: /\.pug$/,
-        oneOf: [
-          // this applies to <template lang="pug"> in Vue components
-          {
-            resourceQuery: /^\?vue/,
-            use: ['pug-plain-loader']
-          },
-          // this applies to pug imports inside JavaScript
-          {
-            use: ['raw-loader', 'pug-plain-loader']
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Style Injection
-
-Client-side style injection now injects all styles upfront to ensure consistent behavior between development and extracted mode.
-
-Note the injection order is still not guaranteed, so you should avoid writing CSS that relies on insertion order.
+`vue-loader` is a loader for [webpack](https://webpack.js.org/) that allows you to author Vue components in a format called [Single-File Components (SFCs)](./spec.md):
 
-### PostCSS
+``` vue
+<template>
+  <div class="example">{{ msg }}</div>
+</template>
 
-`vue-loader` no longer auto applies PostCSS transforms. To use PostCSS, configure `postcss-loader` the same way you would for normal CSS files.
-
-### CSS Modules
-
-CSS Modules now need to be explicitly configured via `css-loader` options. The `module` attribute on `<style>` tags is still needed for locals injection into the component.
-
-The good news is that you can now configure `localIdentName` in one place:
-
-``` js
-{
-  module: {
-    rules: [
-      {
-        test: /\.css$/,
-        use: [
-          {
-            loader: 'vue-style-loader'
-          },
-          {
-            loader: 'css-loader',
-            options: {
-              modules: true,
-              localIdentName: '[local]_[hash:base64:8]'
-            }
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-If you only want to use CSS Modules in some of your Vue components, you can use a `oneOf` rule and check for the `module` string in resourceQuery:
-
-``` js
-{
-  test: /\.css$/,
-  oneOf: [
-    // this matches <style module>
-    {
-      resourceQuery: /module/,
-      use: [
-        'vue-style-loader',
-        {
-          loader: 'css-loader',
-          options: {
-            modules: true,
-            localIdentName: '[local]_[hash:base64:5]'
-          }
-        }
-      ]
-    },
-    // this matches plain <style> or <style scoped>
-    {
-      use: [
-        'vue-style-loader',
-        'css-loader'
-      ]
+<script>
+export default {
+  data () {
+    return {
+      msg: 'Hello world!'
     }
-  ]
+  }
 }
-```
+</script>
 
-## CSS Extraction
-
-Works the same way as you'd configure it for normal CSS. Example usage with [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin):
-
-``` js
-{
-  module: {
-    rules: [
-      {
-        test: /\.vue$/,
-        use: 'vue-loader'
-      },
-      {
-        test: /\.css$/,
-        // or ExtractTextWebpackPlugin.extract(...)
-        use: [
-          MiniCssExtractPlugin.loader,
-          'css-loader'
-        ]
-      }
-    ]
-  },
-  plugins: [
-    new MiniCssExtractPlugin({
-      filename: 'output.css'
-    })
-  ]
+<style>
+.example {
+  color: red;
 }
+</style>
 ```
 
-## SSR externals
-
-In SSR, we typically use `webpack-node-externals` to exclude npm dependencies from the server build. If you need to import CSS from an npm dependency, the previous solution was using a whitelist like this:
-
-``` js
-// webpack config
-externals: nodeExternals({
-  whitelist: /\.css$/
-})
-```
-
-With v15, imports for `<style src="dep/foo.css">` now has resourceQuery strings appended at the end of the request, so you need to update the above to:
-
-``` js
-externals: nodeExternals({
-  whitelist: [/\.css$/, /\?vue&type=style/]
-})
-```
-
-## Options Deprecation
-
-The following options have been deprecated and should be configured using normal webpack module rules:
-
-- `loader`
-- `preLoaders`
-- `postLoaders`
-- `postcss`
-- `cssSourceMap`
-- `buble`
-- `extractCSS`
-- `template`
-
-The following options have been deprecated and should be configured using the new `compilerOptions` option:
-
-- `preserveWhitespace` (use `compilerOptions.preserveWhitespace`)
-- `compilerModules` (use `compilerOptions.modules`)
-- `compilerDirectives` (use `compilerOptions.directives`)
-
-The following option has been renamed:
-
-- `transformToRequire` (now renamed to `transformAssetUrls`)
-
-The following option has been changed to resourceQuery:
-
-- `shadowMode` (now use inline resource queries, e.g. `foo.vue?shadow`)
+There are many cool features provided by `vue-loader`:
 
-## New Complete Options List
+- Allows using other webpack loaders for each part of a Vue component, for example Sass for `<style>` and Pug for `<template>`;
+- Allows custom blocks in a `.vue` file that can have custom loader chains applied to them;
+- Treat static assets referenced in `<style>` and `<template>` as module dependencies and handle them with webpack loaders;
+- Simulate scoped CSS for each component;
+- State-preserving hot-reloading during development.
 
-- `compiler`
-- `compilerOptions`
-- `transpileOptions`
-- `transformAssetUrls`
-- `optimizeSSR`
-- `hotReload`
-- `productionMode`
+In a nutshell, the combination of webpack and `vue-loader` gives you a modern, flexible and extremely powerful front-end workflow for authoring Vue.js applications.