mirror/vue-cli
1
0
Fork 0
mirror of https://github.com/vuejs/vue-cli.git synced 2026-04-23 13:29:09 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs: wip

Browse Source
This commit is contained in:
Evan You
2018-06-07 13:24:59 -04:00
parent 0b9c837108
commit 97787947b9
12 changed files with 243 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.vuepress/config.js
+1 -1
View File
@@ -3,7 +3,7 @@ module.exports = {
'/': {
lang: 'en-US',
title: 'Vue CLI',
description: 'Standard Tooling for Vue.js Projects'
description: '🛠️ Standard Tooling for Vue.js Development'
}
},
serviceWorker: true,
docs/.vuepress/override.styl
+2
View File
@@ -0,0 +1,2 @@
.home .hero img
max-height 180px
docs/.vuepress/public/logo.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.4 KiB

docs/.vuepress/public/vue-cli-ui-preview.gif
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 217 KiB

docs/README.md
+27 -27
View File
@@ -1,30 +1,30 @@
# Introduction
---
home: true
heroImage: /logo.png
actionText: Get Started →
actionLink: /guide/
features:
- title: Feature Rich
details: Out-of-the-box support for Babel, TypeScript, ESLint, PostCSS, PWA, Unit Testing & End-to-end Testing.
- title: Extensible
details: The plugin system allows the community to build and share reusable solutions to common needs.
- title: No Need to Eject
details: Vue CLI is fully configurable without the need for ejecting. This allows your project to stay up-to-date for the long run.
- title: GUI on top of the CLI
details: Create, develop and manage your projects through an accompanying graphical user interface.
- title: Instant Prototyping
details: Instantly prototype new ideas with a single Vue file.
- title: Future Ready
details: Effortlessly ship native ES2015 code for modern browsers, or build your vue components as native web components.
footer: MIT Licensed | Copyright © 2018-present Evan You
---
Vue CLI is a full system for rapid Vue.js development, providing:
## Getting Started
- Interactive project scaffolding via `@vue/cli`.
- Zero config rapid prototyping via `@vue/cli` + `@vue/cli-service-global`.
- A runtime dependency (`@vue/cli-service`) that is:
- Upgradeable;
- Built on top of webpack, with sensible defaults;
- Configurable via in-project config file;
- Extensible via plugins
- A rich collection of official plugins integrating the best tools in the frontend ecosystem.
``` bash
npm install -g @vue/cli
# OR
yarn global add @vue/cli
Vue CLI aims to be the standard tooling baseline for the Vue ecosystem. It ensures the various build tools work smoothly together with sensible defaults so you can focus on writing your app instead of spending days wrangling with configurations. At the same time, it still offers the flexibility to tweak the config of each tool without the need for ejecting.
- Overview
- CLI
- Creating a Project
- Plugins and Presets
- Instant Prototyping
- CLI UI
- Development
- The CLI Service
- Browser Compatibility
- HTML and static assets
- Mode and Environment Variables
- Git Hooks
- Building as a Library
- Building as Web Components
- Deployment
vue create my-project
```
docs/config/README.md
+102 -46
View File
@@ -50,6 +50,13 @@ module.exports = {
// CSS related options
css: {
//
// By defualt only files ending with *.modules.[ext] are loaded as
// CSS modules. Setting this to true enables CSS modules for all style
// file types.
// This option does not affect *.vue files.
modules: false,
// extract CSS in components into a single CSS file (only in production)
// can also be an object of options to pass to extract-text-webpack-plugin
extract: true,
@@ -59,11 +66,13 @@ module.exports = {
// pass custom options to pre-processor loaders. e.g. to pass options to
// sass-loader, use { sass: { ... } }
loaderOptions: {},
// Enable CSS modules for all css / pre-processor files.
// This option does not affect *.vue files.
modules: false
loaderOptions: {
css: {},
postcss: {},
less: {},
sass: {},
stylus: {}
}
},
// use thread-loader for babel & TS in production build
@@ -113,6 +122,10 @@ module.exports = {
The object will be merged into the final webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
::: warning
Some webpack options are set based on values in `vue.config.js` and should not be mutated directly. For example, instead of modifying `output.path`, you should use the `outputDir` option in `vue.config.js`; instead of modifying `output.publicPath`, you should use the `baseUrl` option in `vue.config.js`. This is because the values in `vue.config.js` will be used in multiple places inside the config to ensure everything works properly together.
:::
If you need conditional behavior based on the environment, or want to directly mutate the config, use a function (which will be lazy evaluated after the env variables are set). The function receives the resolved config as the argument. Inside the function, you can either mutate the config directly, OR return an object which will be merged:
``` js
@@ -134,41 +147,29 @@ The internal webpack config is maintained using [webpack-chain](https://github.c
This allows us finer-grained control over the internal config. Here are some examples:
#### Transpiling a Dependency Module
By default the Babel configuration skips
#### Modifying Options of a Loader
``` js
// vue.config.js
module.exports = {
chainWebpack: config => {
config.module
.rule('js')
.include
.add(/some-module-to-transpile/)
}
}
```
#### Modifying Loader Options
``` js
// vue.config.js
module.exports = {
chainWebpack: config => {
config.module
.rule('scss')
.use('sass-loader')
.tap(options =>
merge(options, {
includePaths: [path.resolve(__dirname, 'node_modules')],
config
.rule('vue')
.use('vue-loader')
.loader('vue-loader')
.tap(options => {
// modify the options...
return options
})
)
}
}
```
#### Adding a new loader example
::: tip
For CSS related loaders, it's recommended to use [css.loaderOptions](#passing-options-to-pre-processor-loaders) instead of directly targeting loaders via chaining. This is because there are multiple rules for each CSS file type and `css.loaderOptions` ensures you can affect all rules in one single place.
:::
#### Adding a New Loader
``` js
// vue.config.js
@@ -185,7 +186,7 @@ module.exports = {
}
```
#### Replace existing Base Loader
#### Replacing Loaders of a Rule
If you want to replace an existing [Base Loader](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-service/lib/config/base.js), for example using `vue-svg-loader` to inline SVG files instead of loading the file:
@@ -193,15 +194,22 @@ If you want to replace an existing [Base Loader](https://github.com/vuejs/vue-cl
// vue.config.js
module.exports = {
chainWebpack: config => {
config.module
.rule('svg')
.use('file-loader')
const svgRule = config.module.rule('svg')
// clear all existing loaders.
// if you don't do this, the loader below will be appended to
// existing loaders of the rule.
svgRule.uses.clear()
// add replacement loader(s)
svgRule
.use('vue-svg-loader')
.loader('vue-svg-loader')
}
}
```
#### Modifying Plugin Options
#### Modifying Options of a Plugin
``` js
// vue.config.js
@@ -242,7 +250,9 @@ Since `@vue/cli-service` abstracts away the webpack config, it may be more diffi
`vue-cli-service` exposes the `inspect` command for inspecting the resolved webpack config. The global `vue` binary also provides the `inspect` command, and it simply proxies to `vue-cli-service inspect` in your project.
The command prints to stdout by default, so you can redirect that into a file for easier inspection:
The command will print the resolved webpack config to stdout, which also contains hints on how to access rules and plugins via chaining.
You can redirect the output into a file for easier inspection:
``` bash
vue inspect > output.js
@@ -250,13 +260,27 @@ vue inspect > output.js
Note the output is not a valid webpack config file, it's a serialized format only meant for inspection.
You can also inspect a certain path of the config to narrow it down:
You can also inspect a subset of the config by specifying a path:
``` bash
# only inspect the first rule
vue inspect module.rules.0
```
Or, target a named rule or plugin:
``` bash
vue inspect --rule vue
vue inspect --plugin html
```
Finally, you can list all named rules and plugins:
``` bash
vue inspect --rules
vue inspect --plugins
```
### Using Resolved Config as a File
Some external tools may need access to the resolved webpack config as a file, for example IDEs or command line tools that expects a webpack config path. In that case you can use the following path:
@@ -275,6 +299,10 @@ Vue CLI projects comes with support for [PostCSS](http://postcss.org/), [CSS Mod
Vue CLI uses PostCSS internally, and enables [autoprefixer](https://github.com/postcss/autoprefixer) by default. You can configure PostCSS via `.postcssrc` or any config source supported by [postcss-load-config](https://github.com/michael-ciniawsky/postcss-load-config).
You can also configure `postcss-loader` via `css.loaderOptions.postcss` in `vue.config.js`.
The [autoprefixer](https://github.com/postcss/autoprefixer) plugin is enabled by default. To configure the browser targets, use the [browserslist](../guide/browser-compatibility.html#browserslist) field in `package.json`.
### CSS Modules
You can [use CSS Modules in `*.vue` files](https://vue-loader.vuejs.org/en/features/css-modules.html) out of the box with `<style module>`.
@@ -295,7 +323,20 @@ import styles from './foo.css?module'
import sassStyles from './foo.scss?module'
```
If you wish to customize the generated CSS modules class names, you can do so via the `css.localIdentName` option in `vue.config.js`.
If you wish to customize the generated CSS modules class names, you can do so via `css.loaderOptions.css` in `vue.config.js`. All `css-loader` options are supported here, for example `localIdentName` and `camelCase`:
``` js
// vue.config.js
module.exports = {
css: {
loaderOptions: {
css: {
camelCase: 'only'
}
}
}
}
```
### Pre-Processors
@@ -324,22 +365,27 @@ const fs = require('fs')
module.exports = {
css: {
loaderOptions: {
// pass options to sass-loader
sass: {
data: fs.readFileSync('src/variables.scss', 'utf-8')
// @/ is an alias to src/
// so this assumes you have a file named `src/variables.scss`
data: `@import "@/variables.scss";`
}
}
}
}
```
Loaders can be configured via `loaderOptions` include:
- [css-loader](https://github.com/webpack-contrib/css-loader)
- [postcss-loader](https://github.com/postcss/postcss-loader)
- [sass-loader](https://github.com/webpack-contrib/sass-loader)
- [less-loader](https://github.com/webpack-contrib/less-loader)
- [stylus-loader](https://github.com/shama/stylus-loader)
This is preferred over manually tapping into specific loaders, because these options will be shared across all rules that are related to it.
## browserslist
You will notice a `browserslist` field in `package.json` specifying a range of browsers the project is targeting. This value will be used by `babel-preset-env` and `autoprefixer` to automatically determine the JavaScript polyfills and CSS vendor prefixes needed.
See [here](https://github.com/ai/browserslist) for how to specify browser ranges.
## Dev Server
`vue-cli-service serve` starts a dev server based on [webpack-dev-server](https://github.com/webpack/webpack-dev-server). It comes with hot-module-replacement (HMR) out of the box.
@@ -401,10 +447,16 @@ module.exports = {
## Babel
Babel can be configured via `.babelrc` or the `babel` field in `package.json`.
Babel can be configured via `babel.config.js`.
::: tip
Vue CLI uses `babel.config.js` which is a new config format in Babel 7. Unlike `.babelrc` or the `babel` field in `package.json`, this config file does not use a file-location based resolution, and is applied consistently to any file under project root, including dependencies inside `node_modules`. It is recommended to always use `babel.config.js` instead of other formats in Vue CLI projects.
:::
All Vue CLI apps use `@vue/babel-preset-app`, which includes `babel-preset-env`, JSX support and optimized configuration for minimal bundle size overhead. See [its docs](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app) for details and preset options.
Also see the [Polyfills](../guide/browser-compatibility.md#polyfills) section in guide.
## ESLint
ESLint can be configured via `.eslintrc` or `eslintConfig` field in `package.json`.
@@ -436,3 +488,7 @@ See [@vue/cli-plugin-e2e-cypress](https://github.com/vuejs/vue-cli/tree/dev/pack
### Nightwatch
See [@vue/cli-plugin-e2e-nightwatch](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch) for more details.
## Browser Targets
See the [Browser Compatibility](../guide/browser-compatibility.md#browserslist) section in guide.
docs/guide/README.md
+17 -25
View File
@@ -1,5 +1,5 @@
---
sidebarDepth: 1
sidebarDepth: 0
---
# Overview
@@ -19,38 +19,30 @@ Vue CLI aims to be the standard tooling baseline for the Vue ecosystem. It ensur
## Understanding the Architecture
There are several moving parts of Vue CLI - if you look at the [source code](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue), you will find that it is a monorepo containing a number of separately published packages.
### CLI
The CLI is a installed globally npm package and provides the `vue` command in your terminal:
``` bash
npm install -g @vue/cli
vue create my-project
```
The CLI (`@vue/cli`) is a globally installed npm package and provides the `vue` command in your terminal. It provides the ability to quickly scaffold a new project via `vue create`, or instantly prototype new ideas via `vue serve`. You can also manage your projects using a graphical user interface via `vue ui`. We will walk through what it can do in the next few sections of the guide.
### CLI Service
`@vue/cli-service` is an npm package installed locally into every project created by `@vue/cli`. It contains the core service that loads other plugins, resolves the final webpack config, and provides the `vue-cli-service` binary to your project. If you are familiar with [create-react-app](https://github.com/facebookincubator/create-react-app), `@vue/cli-service` is essentially the equivalent of `react-scripts`, but more flexible.
The CLI Service (`@vue/cli-service`) is a development dependency. It's an npm package installed locally into every project created by `@vue/cli`.
See [CLI Service docs](./cli-service.md) for all available commands.
The CLI Service is built on top of [webpack](http://webpack.js.org/) and [webpack-dev-server](https://github.com/webpack/webpack-dev-server). It contains:
- The core service that loads other CLI Plugins;
- An internal webpack config that is optimized for most apps;
- The `vue-cli-service` binary inside the project, which comes with the basic `serve`, `build` and `inspect` commands.
If you are familiar with [create-react-app](https://github.com/facebookincubator/create-react-app), `@vue/cli-service` is roughly the equivalent of `react-scripts`, although the feature set is different.
The section on [CLI Service](./cli-service.md) covers its detailed usage.
### CLI Plugins
Each project will likely contain a number of
CLI Plugins are npm packages that provide optional features to your Vue CLI projects, such as Babel/TypeScript trasnpilation, ESLint integration, unit testing, and end-to-end testing. It's easy to spot a Vue CLI plugin as their names start with either `@vue/cli-plugin-` (for built-in plugins) or `vue-cli-plugin-` (for community plugins).
### Presets
When you run the `vue-cli-service` binary inside your project, it automatically resolves and loads all CLI Plugins listed in your project's `package.json`.
A preset
## Development Features
- webpack
- webpack-dev-server
- pre-processors
- git hooks
## Configuration without Ejecting
Projects created from vue create are ready to go out-of-the-box. The plugins are designed to work with one another so in most cases, all you need to do is pick the features you want during the interactive prompts.
However, we also understand that it's impossible to cater to every possible need, and the need of a project may also change over time. Projects created by Vue CLI allows you to configure almost every aspect of the tooling without ever needing to eject. Check out the [Config Reference](../config/) for more details.
Plugins can be included as part of your project creation process or added into the project later. They can also be grouped into reusable presets. We will discuss these in more depth in the [Plugins and Presets](./plugins-and-presets.md) section.
docs/guide/browser-compatibility.md
+14
View File
@@ -1 +1,15 @@
# Browser Compatibility
## browserslist
You will notice a `browserslist` field in `package.json` specifying a range of browsers the project is targeting. This value will be used by `babel-preset-env` and `autoprefixer` to automatically determine the JavaScript polyfills and CSS vendor prefixes needed.
See [here](https://github.com/ai/browserslist) for how to specify browser ranges.
::: tip Note on Vendor-prefixed CSS Rules
In the production build, Vue CLI optimizes your CSS and will drop unnecessary vendor-prefixed CSS rules based on your browser targets. With [autoprefixer](https://github.com/postcss/autoprefixer) enabled by default, you should always use only non-prefixed CSS rules.
:::
## Polyfills
## Modern Mode
docs/guide/build-targets.md
+3 -1
View File
@@ -1,8 +1,10 @@
# Build Targets
When you run `vue-cli-service build`, you can specify different build targets via the `--target` option. This allows you to use the same code base to produce different builds for different use cases.
## App
App mode is the default mode. In this mode:
App is the default build target. In this mode:
- `index.html` with asset and resource hints injection
- vendor libraries split into a separate chunk for better caching
docs/guide/cli-service.md
+51 -15
View File
@@ -9,13 +9,27 @@ This is what you will see in the `package.json` of a project using the default p
``` json
{
"scripts": {
"serve": "vue-cli-service serve --open",
"serve": "vue-cli-service serve",
"build": "vue-cli-service build"
}
}
```
## serve
You can invoke these scripts using either npm or Yarn:
``` bash
npm run serve
# OR
yarn serve
```
If you have [npx](https://github.com/zkat/npx) available (should be bundled with an update-to-date version of npm), you can also invoke the binary directly with:
``` bash
npx vue-cli-service serve
```
## vue-cli-service serve
```
Usage: vue-cli-service serve [options]
@@ -30,7 +44,11 @@ Options:
--https use https (default: false)
```
## build
The `serve` command starts a dev server (based on [webpack-dev-server](https://github.com/webpack/webpack-dev-server)) that comes with Hot-Module-Replacement (HMR) working out of the box.
In addition to the command line flags, you can also configure the dev server using the [devServer](../config/#devserver) field in `vue.config.js`.
## vue-cli-service build
```
Usage: vue-cli-service build [options] [entry|pattern]
@@ -46,17 +64,9 @@ Options:
`vue-cli-service build` produces a production-ready bundle in the `dist/` directory, with minification for JS/CSS/HTML and auto vendor chunk splitting for better caching. The chunk manifest is inlined into the HTML.
### Caching and Parallel Mode
- `cache-loader` is enabled for Vue/Babel/TypeScript compilations by default. Files are cached inside `node_modules/.cache` - if running into compilation issues, always try deleting the cache directory first.
- `thread-loader` will be enabled for Babel/TypeScript transpilation when the machine has more than 1 CPU cores.
## Building as Library or Web Components
It is also possible to build any component(s) inside your project as a library or as web components. See [Build Targets](./build-targets.md) for more details.
## inspect
## vue-cli-service inspect
```
Usage: vue-cli-service inspect [options] [...paths]
@@ -66,20 +76,46 @@ Options:
--mode specify env mode (default: development)
```
You can use `vue-cli-service inspect` to inspect the webpack config inside a Vue CLI project. See [Inspecting Webpack Config](../config/#inspecting-the-projects-webpack-config) for more details.
You can use `vue-cli-service inspect` to inspect the webpack config inside a Vue CLI project. See [Inspecting Webpack Config](../config/#inspecting-the-project-s-webpack-config) for more details.
## Checking All Available Commands
Some CLI plugins will inject additional commands to `vue-cli-service`. For example, `@vue/cli-plugin-eslint` injects the `vue-cli-service lint` command. You can see all injected commands by running:
``` bash
./node_modules/.bin/vue-cli-service help
npx vue-cli-service help
```
You can also learn about the available options of each command with:
``` bash
./node_modules/.bin/vue-cli-service help [command]
npx vue-cli-service help [command]
```
## Caching and Parallelization
- `cache-loader` is enabled for Vue/Babel/TypeScript compilations by default. Files are cached inside `node_modules/.cache` - if running into compilation issues, always try deleting the cache directory first.
- `thread-loader` will be enabled for Babel/TypeScript transpilation when the machine has more than 1 CPU cores.
## Git Hooks
When installed, `@vue/cli-service` also installs [yorkie](https://github.com/yyx990803/yorkie), which allows you to easily specify Git hooks using the `gitHooks` field in your `package.json`:
``` json
{
"gitHooks": {
"pre-commit": "lint-staged"
}
}
```
::: warning
`yorkie` is a fork of [`husky`](https://github.com/typicode/husky) and is not compatible with the latter.
:::
## Configuration without Ejecting
Projects created via `vue create` are ready to go without the need for additional configuration. The plugins are designed to work with one another so in most cases, all you need to do is pick the features you want during the interactive prompts.
However, we also understand that it's impossible to cater to every possible need, and the need of a project may also change over time. Projects created by Vue CLI allows you to configure almost every aspect of the tooling without ever needing to eject. Check out the [Config Reference](../config/) for more details.
docs/guide/creating-a-project.md
+4
View File
@@ -32,6 +32,10 @@ The default setup is great for quickly prototyping a new project, while the manu
If you chose to manually select features, at the end of the prompts you also have the option to save your selections as a preset so that you can reuse it in the future. We will discuss presets and plugins in the next section.
::: tip
During the project creation process, you may get prompted to use the [Taobao npm registry mirror](https://npm.taobao.org/) for faster dependency installation. You choice will be saved in a file called `~/.vuerc` for future uses. If you wish you change this later, you can do so by editing `~/.vuerc`.
:::
The `vue create` command has a number of options and you can explore them all by running:
``` bash
docs/guide/deployment.md
+22
View File
@@ -1 +1,23 @@
# Deployment
## GitHub Pages
> TODO | Open to contribution.
## GitLab Pages
> TODO | Open to contribution.
## Netlify
> TODO | Open to contribution.
Also checkout [vue-cli-plugin-netlify-lambda](https://github.com/netlify/vue-cli-plugin-netlify-lambda).
## Amazon S3
See [vue-cli-plugin-s3-deploy](https://github.com/multiplegeorges/vue-cli-plugin-s3-deploy).
## Heroku
> TODO | Open to contribution.