Merge pull request #1 from vuejs/master

merge with upstream

Author: vanhoavn

docs/book.json

@@ -1,7 +1,7 @@
 {
   "title": "vue-loader",
   "gitbook": ">3.0.0",
-  "plugins": ["edit-link", "theme-vuejs@git+https://github.com/pearofducks/gitbook-plugin-theme-vuejs.git", "-fontsettings", "github"],
+  "plugins": ["edit-link", "theme-vuejs", "-fontsettings", "github"],
   "pluginsConfig": {
     "edit-link": {
       "base": "https://github.com/vuejs/vue-loader/tree/master/docs",

docs/en/README.md

@@ -21,9 +21,9 @@ In a nutshell, the combination of Webpack and `vue-loader` gives you a modern, f
 
 If you are already familiar with Webpack, feel free to skip the following explanation. But for those of you who are new to Webpack, here's a quick intro:
 
-[Webpack](http://webpack.github.io/) is a module bundler. It takes a bunch of files, treating each as a module, figuring out the dependencies between them, and bundle them into static assets that are ready for deployment.
+[Webpack](https://webpack.github.io/) is a module bundler. It takes a bunch of files, treating each as a module, figuring out the dependencies between them, and bundle them into static assets that are ready for deployment.
 
-![webpack](http://webpack.github.io/assets/what-is-webpack.png)
+![webpack](https://webpack.github.io/assets/what-is-webpack.png)
 
 For a basic example, imagine we have a bunch of CommonJS modules. They cannot run directly inside the browser, so we need to "bundle" them into a single file that can be included via a `<script>` tag. Webpack can follow the dependencies of the `require()` calls and do that for us.
 

docs/en/SUMMARY.md

@@ -26,6 +26,8 @@
   - [cssSourceMap](options.md#csssourcemap)
   - [esModule](options.md#esmodule)
   - [preserveWhitespace](options.md#preservewhitespace)
+  - [compilerModules](options.md#compilermodules)
+  - [compilerDirectives](options.md#compilerdirectives)
   - [transformToRequire](options.md#transformtorequire)
   - [buble](options.md#buble)
   - [extractCSS](options.md#extractcss)

docs/en/configurations/pre-processors.md

@@ -56,7 +56,7 @@ Then add the following webpack rule:
 }
 ```
 
-As an example, if you are using [vuejs-templates/webpack](https://github.com/vuejs-templates/webpack), modify `build/util.js` like so:
+As an example, if you are using [vuejs-templates/webpack](https://github.com/vuejs-templates/webpack), modify `build/utils.js` like so:
 
 ``` js
 scss: generateLoaders('sass').concat(

docs/en/features/hot-reload.md

@@ -4,4 +4,18 @@
 
 ![hot-reload](http://blog.evanyou.me/images/vue-hot.gif)
 
+## State Preservation Rules
+
+- When editing the `<template>` of a component, instances of the edited component will re-render in place, preserving all current private state. This is possible because templates are compiled into new render functions that produce no side-effects.
+
+- When editing the `<script>` part of a component, instances of the edited component will be destroyed and re-created in place. (State of the other components in the app are preserved) This is because `<script>` can include lifecycle hooks that may produce side-effects, so a "reload" instead of re-render is required to ensure consistent behavior. This also means you need to be careful about global side effects such as timers inside your components lifecycle hooks. Sometimes you may need to do a full-page reload if your component produces global side-effects.
+
+- `<style>` hot reload operates on its own via `vue-style-loader`, so it doesn't affect application state.
+
+## Usage
+
 When scaffolding the project with `vue-cli`, Hot Reload is enabled out-of-the-box.
+
+When manually setting up your project, hot-reload is enabled automatically when you serve your project with `webpack-dev-server --hot`.
+
+Advanced users may want to check out [vue-hot-reload-api](https://github.com/vuejs/vue-hot-reload-api), which is used internally by `vue-loader`.

docs/en/features/scoped-css.md

@@ -28,40 +28,50 @@ Into the following:
 </template>
 ```
 
-#### Notes
+## Tips
 
-1. You can include both scoped and non-scoped styles in the same component:
+### Mixing Local and Global Styles
 
-  ``` html
-  <style>
-  /* global styles */
-  </style>
+You can include both scoped and non-scoped styles in the same component:
 
-  <style scoped>
-  /* local styles */
-  </style>
-  ```
+``` html
+<style>
+/* global styles */
+</style>
+
+<style scoped>
+/* local styles */
+</style>
+```
+
+### Child Component Root Elements
+
+With `scoped`, the parent component's styles will not leak into child components. However, a child component's root node will be affected by both the parent's scoped CSS and the child's scoped CSS. This is by design so that the parent can style the child root element for layout purposes.
+
+### Deep Selectors
+
+If you want a selector in `scoped` styles to be "deep", i.e. affecting child components, you can use the `>>>` combinator:
+
+``` html
+<style scoped>
+.a >>> .b { /* ... */ }
+</style>
+```
+
+The above will be compiled into:
+
+``` css
+.a[data-v-f3f3eg9] .b { /* ... */ }
+```
 
-2. A child component's root node will be affected by both the parent's scoped CSS and the child's scoped CSS.
+Some pre-processors, such as SASS, may not be able to parse `>>>` properly. In those cases you can use the `/deep/` combinator instead - it's an alias for `>>>` and works exactly the same.
 
-3. Partials are not affected by scoped styles.
+### Dynamically Generated Content
 
-4. **Scoped styles do not eliminate the need for classes**. Due to the way browsers render various CSS selectors, `p { color: red }` will be many times slower when scoped (i.e. when combined with an attribute selector). If you use classes or ids instead, such as in `.example { color: red }`, then you virtually eliminate that performance hit. [Here's a playground](http://stevesouders.com/efws/css-selectors/csscreate.php) where you can test the differences yourself.
+DOM content created with `v-html` are not affected by scoped styles, but you can still style them using deep selectors.
 
-5. **Be careful with descendant selectors in recursive components!** For a CSS rule with the selector `.a .b`, if the element that matches `.a` contains a recursive child component, then all `.b` in that child component will be matched by the rule.
+### Also Keep in Mind
 
-6. If you need nested selectors in `scoped` styles, you will have to use `>>>` operator for CSS and `/deep/` for `scss`:
+- **Scoped styles do not eliminate the need for classes**. Due to the way browsers render various CSS selectors, `p { color: red }` will be many times slower when scoped (i.e. when combined with an attribute selector). If you use classes or ids instead, such as in `.example { color: red }`, then you virtually eliminate that performance hit. [Here's a playground](https://stevesouders.com/efws/css-selectors/csscreate.php) where you can test the differences yourself.
 
-    ``` html
-    <style scoped>
-    .a >>> .b {
-    
-    }
-    </style>
-    
-    <style lang="scss" scoped>
-    .a /deep/ .b {
-    
-    }
-    </style>
-    ```
+- **Be careful with descendant selectors in recursive components!** For a CSS rule with the selector `.a .b`, if the element that matches `.a` contains a recursive child component, then all `.b` in that child component will be matched by the rule.

docs/en/options.md

@@ -137,6 +137,22 @@ module.exports = {
 
   If set to `false`, the whitespaces between HTML tags in templates will be ignored.
 
+### compilerModules
+
+- type: `Array<ModuleOptions>`
+- default: `[]`
+
+  Configure `modules` options for `vue-template-compiler`. In about details, see more [`modules` option](https://github.com/vuejs/vue/blob/dev/packages/vue-template-compiler/README.md#compilercompiletemplate-options) of `vue-template-compiler`.
+
+### compilerDirectives
+
+- type: `{ [tag: string]: Function }`
+- default: `{}` (v13.0.5+)
+
+  > version note: in v12.x, supported in v12.2.3+
+
+  Configure `directives` options for `vue-template-compiler`, In about details, see more [`directives` option](https://github.com/vuejs/vue/blob/dev/packages/vue-template-compiler/README.md#compilercompiletemplate-options) of `vue-template-compiler`.
+
 ### transformToRequire
 
 - type: `{ [tag: string]: string | Array<string> }`

docs/en/workflow/linting.md

@@ -1,6 +1,6 @@
 # Linting
 
-You may have been wondering how do you lint your code inside `*.vue` files, since they are not JavaScript. We will assume you are using [ESLint](http://eslint.org/) (if you are not, you should!).
+You may have been wondering how do you lint your code inside `*.vue` files, since they are not JavaScript. We will assume you are using [ESLint](https://eslint.org/) (if you are not, you should!).
 
 You will also need the [eslint-plugin-html](https://github.com/BenoitZugmeyer/eslint-plugin-html) which supports extracting and linting the JavaScript inside `*.vue` files.
 

docs/en/workflow/testing.md

@@ -2,9 +2,9 @@
 
 > The [webpack vue-cli template](https://github.com/vuejs-templates/webpack) offers pre-configured unit testing and e2e testing setups for you.
 
-When testing `*.vue` files, we cannot use a plain CommonJS-based test runner because it won't know how to handle `*.vue` files. Instead, we still use Webpack + vue-loader to bundle our test files. The recommended setup is using [Karma](http://karma-runner.github.io/0.13/index.html) and [karma-webpack](https://github.com/webpack/karma-webpack).
+When testing `*.vue` files, we cannot use a plain CommonJS-based test runner because it won't know how to handle `*.vue` files. Instead, we still use Webpack + vue-loader to bundle our test files. The recommended setup is using [Karma](https://karma-runner.github.io/0.13/index.html) and [karma-webpack](https://github.com/webpack/karma-webpack).
 
-Karma is a test runner that launches browsers and runs your tests for you. You can choose what browsers you want to test in and what test framework (e.g. Mocha or Jasmine) you want to use. Here is an example Karma configuration that runs the tests inside [PhantomJS](http://phantomjs.org/) with the [Jasmine](http://jasmine.github.io/edge/introduction.html) test framework:
+Karma is a test runner that launches browsers and runs your tests for you. You can choose what browsers you want to test in and what test framework (e.g. Mocha or Jasmine) you want to use. Here is an example Karma configuration that runs the tests inside [PhantomJS](http://phantomjs.org/) with the [Jasmine](https://jasmine.github.io/edge/introduction.html) test framework:
 
 ``` bash
 npm install\

docs/ja/SUMMARY.md

@@ -26,6 +26,8 @@
   - [cssSourceMap](options.md#csssourcemap)
   - [esModule](options.md#esmodule)
   - [preserveWhitespace](options.md#preservewhitespace)
+  - [compilerModules](options.md#compilermodules)
+  - [compilerDirectives](options.md#compilerdirectives)
   - [transformToRequire](options.md#transformtorequire)
   - [buble](options.md#buble)
   - [extractCSS](options.md#extractcss)

docs/ja/configurations/pre-processors.md

@@ -56,7 +56,7 @@ npm install sass-resources-loader --save-dev
 }
 ```
 
-例として、[vuejs-templates/webpack](https://github.com/vuejs-templates/webpack) を使用している場合、 `build/util.js` を以下のように変更してください:
+例として、[vuejs-templates/webpack](https://github.com/vuejs-templates/webpack) を使用している場合、 `build/utils.js` を以下のように変更してください:
 
 ``` js
 scss: generateLoaders('sass').concat(

docs/ja/features/postcss.md

@@ -1,6 +1,6 @@
 # PostCSS
 
-`vue-loader`により処理されたCSSのアウトプットはスコープされたCSSにに書き換えるために[PostCSS](https://github.com/postcss/postcss) を通します。カスタムされた PostCSSプラグインをプロセスに追加することが出来ます。例えば、[autoprefixer](https://github.com/postcss/autoprefixer) や [CSSNext](http://cssnext.io/)があります。
+`vue-loader`により処理されたCSSのアウトプットはスコープされたCSSに書き換えるために[PostCSS](https://github.com/postcss/postcss) を通します。カスタムされた PostCSSプラグインをプロセスに追加することが出来ます。例えば、[autoprefixer](https://github.com/postcss/autoprefixer) や [CSSNext](http://cssnext.io/)があります。
 
 ## 設定ファイルの使用
 

docs/ja/options.md

@@ -132,10 +132,26 @@ module.exports = {
 ### preserveWhitespace
 
 - 型: `boolean`
-- デフォルトx: `true`
+- デフォルト: `true`
 
   もし `false` に設定されていたら、テンプレート内の HTML タグ間の空白は無視されます。
 
+### compilerModules
+
+- 型: `Array<ModuleOptions>`
+- デフォルト: `[]`
+
+  `vue-template-compiler` の `modules` オプションを設定します。詳細については `vue-template-compiler` の [`modules` option](https://github.com/vuejs/vue/blob/dev/packages/vue-template-compiler/README.md#compilercompiletemplate-options) を参照してください。
+
+### compilerDirectives
+
+- 型: `{ [tag: string]: Function }`
+- デフォルト: `{}` (v13.0.5 以降)
+
+  > バージョンメモ: v12.x においては、v12.2.3 以降からサポートされます。
+
+  `vue-template-compiler` の `directives` オプションを設定します。詳細については `vue-template-compiler` の [`directives` option](https://github.com/vuejs/vue/blob/dev/packages/vue-template-compiler/README.md#compilercompiletemplate-options) を参照してください。
+
 ### transformToRequire
 
 - 型: `{ [tag: string]: string | Array<string> }`

docs/ja/start/spec.md

@@ -51,7 +51,7 @@ export default {
 
 - デフォルトの言語は `js`（`babel-loader` や `buble-loader` が検出される場合、自動的にES2015がサポートされる）
 - それぞれの `*.vue` ファイルは最大で一つの `<script>` ブロックを含みます
-- スクリプトは CommonJS のように処理されます（ Webpack 経由でバンドルされた通常の `.js` モジュールと同じです）。つまり他の依存関係を `recuire()` することができます。そして ES2015 がサポートされ、`import` と `export` 構文を使用することが出来ます
+- スクリプトは CommonJS のように処理されます（ Webpack 経由でバンドルされた通常の `.js` モジュールと同じです）。つまり他の依存関係を `require()` することができます。そして ES2015 がサポートされ、`import` と `export` 構文を使用することが出来ます
 - スクリプトは Vue.js コンポーネントのオプションオブジェクトをエクスポートする必要があります。 `Vue.extend()` によって拡張されたコンストラクタもエクスポートすることが可能ですが、プレーンなオブジェクトが好ましいです
 
 #### `<style>`

docs/ru/README.md

@@ -21,9 +21,9 @@
 
 Если вы уже знакомы с Webpack, можете пропустить дальнейшее объяснение. Для тех же, кому Webpack в новинку, вот краткая вводная:
 
-[Webpack](http://webpack.github.io/) – это сборщик модулей. Он берёт кучу файлов, рассматривая каждый как модуль, разрешает зависимости между ними и собирает их в статические ресурсы, готовые к развёртыванию.
+[Webpack](https://webpack.github.io/) – это сборщик модулей. Он берёт кучу файлов, рассматривая каждый как модуль, разрешает зависимости между ними и собирает их в статические ресурсы, готовые к развёртыванию.
 
-![webpack](http://webpack.github.io/assets/what-is-webpack.png)
+![webpack](https://webpack.github.io/assets/what-is-webpack.png)
 
 В качестве простого примера, представим, что у нас есть набор модулей CommonJS. Они не могут запускаться прямо в браузере, так что нам нужно "собрать" их в единый файл, который можно будет вставить на страницу через тег `<script>`. Webpack может сделать это за нас, следуя инструкциям `require()`.
 

docs/ru/SUMMARY.md

@@ -26,6 +26,8 @@
   - [cssSourceMap](options.md#csssourcemap)
   - [esModule](options.md#esmodule)
   - [preserveWhitespace](options.md#preservewhitespace)
+  - [compilerModules](options.md#compilermodules)
+  - [compilerDirectives](options.md#compilerdirectives)
   - [transformToRequire](options.md#transformtorequire)
   - [buble](options.md#buble)
   - [extractCSS](options.md#extractcss)

docs/ru/configurations/advanced.md

@@ -10,7 +10,7 @@
 
 Чтобы сделать это укажите опцию `loaders` для `vue-loader`:
 
-> Опции `preLoaders` и `postLoaders` доступны только в версиях >=10.3.0
+> Опции `preLoaders` и `postLoaders` доступны только в версиях 10.3.0+
 
 ### Webpack 2.x
 

docs/ru/configurations/pre-processors.md

@@ -37,6 +37,40 @@ npm install sass-loader node-sass --save-dev
 
 Обратитесь к разделу [продвинутой конфигурации загрузчиков](./advanced.md) для получения дополнительной информации о том, как настраивать vue-loader.
 
+#### Загрузка глобального файла настроек
+
+Часто встречаются просьбы добавить возможность загружать файл настроек в каждом компоненте без необходимости явно импортировать его каждый раз, например для использования SCSS-переменных глобально во всех компонентах. Для этого нужно:
+
+``` bash
+npm install sass-resources-loader --save-dev
+```
+
+Затем добавить новое правило в Webpack:
+
+``` js
+{
+  loader: 'sass-resources-loader',
+  options: {
+    resources: path.resolve(__dirname, '../src/style/_variables.scss')
+  }
+}
+```
+
+Например, если вы используете [vuejs-templates/webpack](https://github.com/vuejs-templates/webpack), измените файл `build/utils.js` таким образом:
+
+``` js
+scss: generateLoaders('sass').concat(
+  {
+    loader: 'sass-resources-loader',
+    options: {
+      resources: path.resolve(__dirname, '../src/style/_variables.scss')
+    }
+  }
+),
+```
+
+В этот файл рекомендуется включать только переменные, примеси и т.п., чтобы предотвратить дублирование CSS в финальных скомпилированных файлах.
+
 ### JavaScript
 
 Весь JavaScript внутри Vue компонентов обрабатывается `babel-loader` по умолчанию. При необходимости это можно изменить: