docs: Merge branch 'docs' into dev

yyx990803 · yyx990803 · commit 1ce40cd247ef · 2018-07-26T22:43:25.000-04:00
diff --git a/docs/guide/browser-compatibility.md b/docs/guide/browser-compatibility.md
@@ -8,7 +8,7 @@ See [here][browserslist] for how to specify browser ranges.
 
 ## Polyfills
 
-A default Vue CLI project uses [@vue/babel-preset-app][babel-preset-env], which uses `@babel/preset-env` and the `browserslist` config to determine the Polyfills needed for your project.
+A default Vue CLI project uses [@vue/babel-preset-app][babel-preset-app], which uses `@babel/preset-env` and the `browserslist` config to determine the Polyfills needed for your project.
 
 By default, it passes [`useBuiltIns: 'usage'`](https://new.babeljs.io/docs/en/next/babel-preset-env.html#usebuiltins-usage) to `@babel/preset-env` which automatically detects the polyfills needed based on the language features used in your source code. This ensures only the minimum amount of polyfills are included in your final bundle. However, this also means **if one of your dependencies has specific requirements on polyfills, by default Babel won't be able to detect it.**
 
@@ -68,4 +68,5 @@ For a Hello World app, the modern bundle is already 16% smaller. In production,
 
 [autoprefixer]: https://github.com/postcss/autoprefixer
 [babel-preset-env]: https://new.babeljs.io/docs/en/next/babel-preset-env.html
+[babel-preset-app]: https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app
 [browserslist]: https://github.com/ai/browserslist
diff --git a/docs/guide/build-targets.md b/docs/guide/build-targets.md
@@ -76,7 +76,9 @@ You can build a single entry as a web component using
 vue-cli-service build --target wc --name my-element [entry]
 ```
 
-This will produce a single JavaScript file (and its minified version) with everything inlined. The script, when included on a page, registers the `<my-element>` custom element, which wraps the target Vue component using `@vue/web-component-wrapper`. The wrapper automatically proxies properties, attributes, events and slots. See the [docs for `@vue/web-component-wrapper`](https://github.com/vuejs/vue-web-component-wrapper) for more details.
+Note that the entry should be a `*.vue` file. Vue CLI will automatically wrap and register the component as a Web Component for you, and there's no need to do this yourself in `main.js`. You can use `main.js` as a demo app solely for development.
+
+The build will produce a single JavaScript file (and its minified version) with everything inlined. The script, when included on a page, registers the `<my-element>` custom element, which wraps the target Vue component using `@vue/web-component-wrapper`. The wrapper automatically proxies properties, attributes, events and slots. See the [docs for `@vue/web-component-wrapper`](https://github.com/vuejs/vue-web-component-wrapper) for more details.
 
 **Note the bundle relies on `Vue` being globally available on the page.**
 
diff --git a/docs/guide/creating-a-project.md b/docs/guide/creating-a-project.md
@@ -8,6 +8,10 @@ To create a new project, run:
 vue create hello-world
 ```
 
+::: warning
+If you are on Windows using Git Bash with minTTY, the interactive prompts will not work. You must launch the command as `winpty vue.cmd create hello-world`.
+:::
+
 You will be prompted to pick a preset. You can either choose the default preset which comes with a basic Babel + ESLint setup, or select "Manually select features" to pick the features you need.
 
 ![CLI preview](/cli-new-project.png)
@@ -43,7 +47,7 @@ Options:
   -i, --inlinePreset <json>       Skip prompts and use inline JSON string as preset
   -m, --packageManager <command>  Use specified npm client when installing dependencies
   -r, --registry <url>            Use specified npm registry when installing dependencies (only for npm)
-  -g, --git [message|false]       Force / skip git intialization, optionally specify initial commit message
+  -g, --git [message|false]       Force / skip git initialization, optionally specify initial commit message
   -f, --force                     Overwrite target directory if it exists
   -c, --clone                     Use git clone when fetching remote preset
   -x, --proxy                     Use specified proxy when creating project
diff --git a/docs/guide/mode-and-env.md b/docs/guide/mode-and-env.md
@@ -18,6 +18,13 @@ VUE_APP_SECRET=secret
 
 Loaded variables will become available to all `vue-cli-service` commands, plugins and dependencies.
 
+::: tip Env Loading Priorities
+
+An env file for a specific mode (e.g. `.env.production`) will take higher priority than a generic one (e.g. `.env`).
+
+In addition, environment variables that already exist when Vue CLI is bootstrapped have the highest priority and will not be overwritten by `.env` files. If you have a default `NODE_ENV` in your environment, you might want to consider removing it.
+:::
+
 ## Modes
 
 **Mode** is an important concept in Vue CLI projects. By default, there are three modes in a Vue CLI project:
diff --git a/packages/@vue/eslint-config-airbnb/README.md b/packages/@vue/eslint-config-airbnb/README.md
@@ -1,3 +1,11 @@
 # @vue/eslint-config-airbnb
 
 > eslint-config-airbnb for vue-cli
+
+This config is specifically designed to be used by `vue-cli` setups
+and is not meant for outside use (it can be used but some adaptations
+on the user side might be needed - for details see the config file).
+
+A part of its design is that this config may implicitly depend on
+other parts of `vue-cli` setups, such as `eslint-plugin-vue` being
+extended in the same resulting config.
diff --git a/packages/@vue/eslint-config-prettier/README.md b/packages/@vue/eslint-config-prettier/README.md
@@ -1,3 +1,11 @@
 # @vue/eslint-config-prettier
 
 > eslint-config-prettier for vue-cli
+
+This config is specifically designed to be used by `vue-cli` setups
+and is not meant for outside use (it can be used but some adaptations
+on the user side might be needed - for details see the config file).
+
+A part of its design is that this config may implicitly depend on
+other parts of `vue-cli` setups, such as `eslint-plugin-vue` being
+extended in the same resulting config.
diff --git a/packages/@vue/eslint-config-standard/README.md b/packages/@vue/eslint-config-standard/README.md
@@ -1,3 +1,11 @@
 # @vue/eslint-config-standard
 
 > eslint-config-standard for vue-cli
+
+This config is specifically designed to be used by `vue-cli` setups
+and is not meant for outside use (it can be used but some adaptations
+on the user side might be needed - for details see the config file).
+
+A part of its design is that this config may implicitly depend on
+other parts of `vue-cli` setups, such as `eslint-plugin-vue` being
+extended in the same resulting config.
diff --git a/packages/@vue/eslint-config-typescript/README.md b/packages/@vue/eslint-config-typescript/README.md
@@ -3,3 +3,11 @@
 > eslint-config-typescript for vue-cli
 
 See [eslint-plugin-typescript](https://github.com/nzakas/eslint-plugin-typescript) for available rules.
+
+This config is specifically designed to be used by `vue-cli` setups
+and is not meant for outside use (it can be used but some adaptations
+on the user side might be needed - for details see the config file).
+
+A part of its design is that this config may implicitly depend on
+other parts of `vue-cli` setups, such as `eslint-plugin-vue` being
+extended in the same resulting config.
diff --git a/packages/@vue/eslint-config-typescript/index.js b/packages/@vue/eslint-config-typescript/index.js
@@ -1,5 +1,9 @@
 module.exports = {
   plugins: ['typescript'],
+  // Prerequisite `eslint-plugin-vue`, being extended, sets
+  // root property `parser` to `'vue-eslint-parser'`, which, for code parsing,
+  // in turn delegates to the parser, specified in `parserOptions.parser`:
+  // https://github.com/vuejs/eslint-plugin-vue#what-is-the-use-the-latest-vue-eslint-parser-error
   parserOptions: {
     parser: require.resolve('typescript-eslint-parser')
   },
