mirror of
https://github.com/vuejs/vue-cli.git
synced 2026-03-11 19:51:52 -05:00
docs: wip
This commit is contained in:
Evan You
93
docs/.vuepress/config.js
Normal file
93
docs/.vuepress/config.js
Normal file
@@ -0,0 +1,93 @@
|
||||
module.exports = {
|
||||
locales: {
|
||||
'/': {
|
||||
lang: 'en-US',
|
||||
title: 'Vue CLI',
|
||||
description: 'Standard Tooling for Vue.js Projects'
|
||||
}
|
||||
},
|
||||
serviceWorker: true,
|
||||
theme: 'vue',
|
||||
themeConfig: {
|
||||
repo: 'vuejs/vue-cli',
|
||||
docsDir: 'docs',
|
||||
docsBranch: 'dev',
|
||||
editLinks: true,
|
||||
sidebarDepth: 3,
|
||||
locales: {
|
||||
'/': {
|
||||
label: 'English',
|
||||
selectText: 'Languages',
|
||||
lastUpdated: 'Last Updated',
|
||||
editLinkText: 'Edit this page on GitHub',
|
||||
nav: [
|
||||
{
|
||||
text: 'Guide',
|
||||
link: '/guide/'
|
||||
},
|
||||
{
|
||||
text: 'Config Reference',
|
||||
link: '/config/'
|
||||
},
|
||||
{
|
||||
text: 'Dev Guide',
|
||||
items: [
|
||||
{ text: 'Plugin Dev Guide', link: '/dev-guide/plugin-dev.md' },
|
||||
{ text: 'UI Plugin Dev Guide', link: '/dev-guide/ui-plugin-dev.md' },
|
||||
{ text: 'UI Localization', link: '/dev-guide/ui-localization.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Plugins',
|
||||
items: [
|
||||
{ text: 'Babel', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-babel' },
|
||||
{ text: 'Typescript', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-typescript' },
|
||||
{ text: 'ESLint', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-eslint' },
|
||||
{ text: 'PWA', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-pwa' },
|
||||
{ text: 'Jest', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-jest' },
|
||||
{ text: 'Mocha', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-mocha' },
|
||||
{ text: 'Cypress', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-cypress' },
|
||||
{ text: 'Nightwatch', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Changelog',
|
||||
link: 'https://github.com/vuejs/vue-cli/blob/dev/CHANGELOG.md'
|
||||
}
|
||||
],
|
||||
sidebar: {
|
||||
'/guide/': [
|
||||
'/guide/',
|
||||
{
|
||||
title: 'CLI',
|
||||
collapsable: false,
|
||||
children: [
|
||||
'/guide/creating-a-project',
|
||||
'/guide/plugins-and-presets',
|
||||
'/guide/prototyping',
|
||||
'/guide/ui'
|
||||
]
|
||||
},
|
||||
{
|
||||
title: 'Development',
|
||||
collapsable: false,
|
||||
children: [
|
||||
'/guide/cli-service',
|
||||
'/guide/browser-compatibility',
|
||||
'/guide/html-and-static-assets',
|
||||
'/guide/mode-and-env',
|
||||
'/guide/build-targets',
|
||||
'/guide/deployment'
|
||||
]
|
||||
}
|
||||
],
|
||||
'/dev-guide/': [
|
||||
'/dev-guide/plugin-dev.md',
|
||||
'/dev-guide/ui-plugin-dev.md',
|
||||
'/dev-guide/ui-localization.md'
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
Before Width: | Height: | Size: 81 KiB After Width: | Height: | Size: 81 KiB |
|
Before Width: | Height: | Size: 22 KiB After Width: | Height: | Size: 22 KiB |
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 16 KiB |
|
Before Width: | Height: | Size: 100 KiB After Width: | Height: | Size: 100 KiB |
|
Before Width: | Height: | Size: 186 KiB After Width: | Height: | Size: 186 KiB |
|
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 42 KiB |
|
Before Width: | Height: | Size: 63 KiB After Width: | Height: | Size: 63 KiB |
|
Before Width: | Height: | Size: 217 KiB After Width: | Height: | Size: 217 KiB |
|
Before Width: | Height: | Size: 66 KiB After Width: | Height: | Size: 66 KiB |
167
docs/README.md
167
docs/README.md
@@ -1,25 +1,4 @@
|
||||
## Table of Contents
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [CLI](#cli)
|
||||
- [CLI Service](#cli-service)
|
||||
- [Conventions](#conventions)
|
||||
- [The Index Page](#the-index-page)
|
||||
- [Static Assets Handling](#static-assets-handling)
|
||||
- [Environment Variables and Modes](#environment-variables-and-modes)
|
||||
- [Configuration](#configuration)
|
||||
- [webpack](#webpack)
|
||||
- [browserslist](#browserslist)
|
||||
- [Dev Server Proxy](#dev-server-proxy)
|
||||
- [Babel](#babel)
|
||||
- [CSS](#css)
|
||||
- [ESLint](#eslint)
|
||||
- [TypeScript](#typescript)
|
||||
- [Unit Testing](#unit-testing)
|
||||
- [E2E Testing](#e2e-testing)
|
||||
- [Development](#development)
|
||||
|
||||
## Introduction
|
||||
# Introduction
|
||||
|
||||
Vue CLI is a full system for rapid Vue.js development, providing:
|
||||
|
||||
@@ -34,132 +13,18 @@ Vue CLI is a full system for rapid Vue.js development, providing:
|
||||
|
||||
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.
|
||||
|
||||
## CLI
|
||||
|
||||
The CLI is installed globally and provides the `vue` command in your terminal:
|
||||
|
||||
``` sh
|
||||
npm install -g @vue/cli
|
||||
vue create my-project
|
||||
```
|
||||
|
||||
See [CLI docs](./cli.md) for all available commands.
|
||||
|
||||
## CLI Service
|
||||
|
||||
`@vue/cli-service` is a dependency 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.
|
||||
|
||||
See [CLI Service docs](./cli-service.md) for all available commands.
|
||||
|
||||
## Conventions
|
||||
|
||||
### The Index Page
|
||||
|
||||
The file `public/index.html` is a template that will be processed with [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin). During build, asset links will be injected automatically. In addition, Vue CLI also automatically injects resource hints (`preload/prefetch`), manifest/icon links (when PWA plugin is used) and inlines the webpack runtime / chunk manifest for optimal performance.
|
||||
|
||||
### Static Assets Handling
|
||||
|
||||
Static assets can be handled in two different ways:
|
||||
|
||||
- Imported in JavaScript or referenced in templates/CSS via relative paths. Such references will be handled by webpack.
|
||||
|
||||
- Placed in the `public` directory and referenced via absolute paths. These assets will simply be copied and not go through webpack.
|
||||
|
||||
See [Static Assets Handling](./assets.md) for more details.
|
||||
|
||||
### Environment Variables and Modes
|
||||
|
||||
It is a common need to customize the app's behavior based on the target environment - for example, you may want the app to use different API endpoints or credentials during development / staging / production environments.
|
||||
|
||||
Vue CLI has comprehensive support for specifying different environment variables using modes and `.env` files.
|
||||
|
||||
See [Environment Variables and Modes](./env.md) for more details.
|
||||
|
||||
## Configuration
|
||||
|
||||
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.
|
||||
|
||||
### vue.config.js
|
||||
|
||||
Many aspects of a Vue CLI project can be configured by placing a `vue.config.js` file at the root of your project. The file may already exist depending on the features you selected when creating the project.
|
||||
|
||||
`vue.config.js` should export an object, for example:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
lintOnSave: true
|
||||
}
|
||||
```
|
||||
|
||||
Check [here](./config.md) for full list of possible options.
|
||||
|
||||
### webpack
|
||||
|
||||
Probably the most common configuration need is tweaking the internal webpack config. Vue CLI provides flexible ways to achieve that without ejecting.
|
||||
|
||||
See [here](./webpack.md) for full details.
|
||||
|
||||
### 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 Proxy
|
||||
|
||||
If your frontend app and the backend API server are not running on the same host, you will need to proxy API requests to the API server during development. This is configurable via the `devServer.proxy` option in `vue.config.js`.
|
||||
|
||||
See [Configuring Proxy](./cli-service.md#configuring-proxy) for more details.
|
||||
|
||||
### Babel
|
||||
|
||||
Babel can be configured via `.babelrc` or the `babel` field in `package.json`.
|
||||
|
||||
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.
|
||||
|
||||
### CSS
|
||||
|
||||
Vue CLI projects comes with support for [PostCSS](http://postcss.org/), [CSS Modules](https://github.com/css-modules/css-modules) and pre-processors including [Sass](https://sass-lang.com/), [Less](http://lesscss.org/) and [Stylus](http://stylus-lang.com/).
|
||||
|
||||
See [here](./css.md) for more details on CSS related configurations.
|
||||
|
||||
### ESLint
|
||||
|
||||
ESLint can be configured via `.eslintrc` or `eslintConfig` field in `package.json`.
|
||||
|
||||
See [@vue/cli-plugin-eslint](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-eslint) for more details.
|
||||
|
||||
### TypeScript
|
||||
|
||||
TypeScript can be configured via `tsconfig.json`.
|
||||
|
||||
See [@vue/cli-plugin-typescript](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-typescript) for more details.
|
||||
|
||||
### Unit Testing
|
||||
|
||||
- #### Jest
|
||||
|
||||
See [@vue/cli-plugin-unit-jest](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-jest) for more details.
|
||||
|
||||
- #### Mocha (via `mocha-webpack`)
|
||||
|
||||
See [@vue/cli-plugin-unit-mocha](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-mocha) for more details.
|
||||
|
||||
### E2E Testing
|
||||
|
||||
- #### Cypress
|
||||
|
||||
See [@vue/cli-plugin-e2e-cypress](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-cypress) for more details.
|
||||
|
||||
- #### Nightwatch
|
||||
|
||||
See [@vue/cli-plugin-e2e-nightwatch](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch) for more details.
|
||||
|
||||
## Development
|
||||
|
||||
- [Contributing Guide](https://github.com/vuejs/vue-cli/blob/dev/.github/CONTRIBUTING.md)
|
||||
- [Plugin Development Guide](https://github.com/vuejs/vue-cli/blob/dev/docs/plugin-dev.md)
|
||||
- [Plugin UI Development Guide](https://github.com/vuejs/vue-cli/blob/dev/docs/plugin-dev-ui.md)
|
||||
- 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
|
||||
|
||||
@@ -1,87 +0,0 @@
|
||||
## `vue.config.js`
|
||||
|
||||
Here are all the available options with default values (all optional):
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
// Project deployment base
|
||||
// By default we assume your app will be deployed at the root of a domain,
|
||||
// e.g. https://www.my-app.com/
|
||||
// If your app is deployed at a sub-path, you will need to specify that
|
||||
// sub-path here. For example, if your app is deployed at
|
||||
// https://www.foobar.com/my-app/
|
||||
// then change this to '/my-app/'
|
||||
baseUrl: '/',
|
||||
|
||||
// where to output built files
|
||||
outputDir: 'dist',
|
||||
|
||||
// where to put static assets (js/css/img/font/...)
|
||||
assetsDir: '',
|
||||
|
||||
// whether to use eslint-loader for lint on save.
|
||||
// valid values: true | false | 'error'
|
||||
// when set to 'error', lint errors will cause compilation to fail.
|
||||
lintOnSave: true,
|
||||
|
||||
// use the full build with in-browser compiler?
|
||||
// https://vuejs.org/v2/guide/installation.html#Runtime-Compiler-vs-Runtime-only
|
||||
runtimeCompiler: false,
|
||||
|
||||
// babel-loader skips `node_modules` deps by default.
|
||||
// explicitly transpile a dependency with this option.
|
||||
transpileDependencies: [/* string or regex */],
|
||||
|
||||
// generate sourceMap for production build?
|
||||
productionSourceMap: true,
|
||||
|
||||
// tweak internal webpack configuration.
|
||||
// see https://github.com/vuejs/vue-cli/blob/dev/docs/webpack.md
|
||||
chainWebpack: () => {},
|
||||
configureWebpack: () => {},
|
||||
|
||||
// CSS related options
|
||||
css: {
|
||||
// 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,
|
||||
|
||||
// enable CSS source maps?
|
||||
sourceMap: false,
|
||||
|
||||
// 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
|
||||
},
|
||||
|
||||
// use thread-loader for babel & TS in production build
|
||||
// enabled by default if the machine has more than 1 cores
|
||||
parallel: require('os').cpus().length > 1,
|
||||
|
||||
// options for the PWA plugin.
|
||||
// see https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-pwa
|
||||
pwa: {},
|
||||
|
||||
// configure webpack-dev-server behavior
|
||||
devServer: {
|
||||
open: process.platform === 'darwin',
|
||||
disableHostCheck: false,
|
||||
host: '0.0.0.0',
|
||||
port: 8080,
|
||||
https: false,
|
||||
hotOnly: false,
|
||||
// See https://github.com/vuejs/vue-cli/blob/dev/docs/cli-service.md#configuring-proxy
|
||||
proxy: null, // string | Object
|
||||
before: app => {}
|
||||
},
|
||||
|
||||
// options for 3rd party plugins
|
||||
pluginOptions: {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
421
docs/config/README.md
Normal file
421
docs/config/README.md
Normal file
@@ -0,0 +1,421 @@
|
||||
---
|
||||
sidebar: auto
|
||||
---
|
||||
|
||||
# Configuration Reference
|
||||
|
||||
## ~/.vuerc
|
||||
|
||||
## vue.config.js
|
||||
|
||||
Here are all the available options with default values (all optional):
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
// Project deployment base
|
||||
// By default we assume your app will be deployed at the root of a domain,
|
||||
// e.g. https://www.my-app.com/
|
||||
// If your app is deployed at a sub-path, you will need to specify that
|
||||
// sub-path here. For example, if your app is deployed at
|
||||
// https://www.foobar.com/my-app/
|
||||
// then change this to '/my-app/'
|
||||
baseUrl: '/',
|
||||
|
||||
// where to output built files
|
||||
outputDir: 'dist',
|
||||
|
||||
// where to put static assets (js/css/img/font/...)
|
||||
assetsDir: '',
|
||||
|
||||
// whether to use eslint-loader for lint on save.
|
||||
// valid values: true | false | 'error'
|
||||
// when set to 'error', lint errors will cause compilation to fail.
|
||||
lintOnSave: true,
|
||||
|
||||
// use the full build with in-browser compiler?
|
||||
// https://vuejs.org/v2/guide/installation.html#Runtime-Compiler-vs-Runtime-only
|
||||
runtimeCompiler: false,
|
||||
|
||||
// babel-loader skips `node_modules` deps by default.
|
||||
// explicitly transpile a dependency with this option.
|
||||
transpileDependencies: [/* string or regex */],
|
||||
|
||||
// generate sourceMap for production build?
|
||||
productionSourceMap: true,
|
||||
|
||||
// tweak internal webpack configuration.
|
||||
// see https://github.com/vuejs/vue-cli/blob/dev/docs/webpack.md
|
||||
chainWebpack: () => {},
|
||||
configureWebpack: () => {},
|
||||
|
||||
// CSS related options
|
||||
css: {
|
||||
// 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,
|
||||
|
||||
// enable CSS source maps?
|
||||
sourceMap: false,
|
||||
|
||||
// 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
|
||||
},
|
||||
|
||||
// use thread-loader for babel & TS in production build
|
||||
// enabled by default if the machine has more than 1 cores
|
||||
parallel: require('os').cpus().length > 1,
|
||||
|
||||
// options for the PWA plugin.
|
||||
// see https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-pwa
|
||||
pwa: {},
|
||||
|
||||
// configure webpack-dev-server behavior
|
||||
devServer: {
|
||||
open: process.platform === 'darwin',
|
||||
disableHostCheck: false,
|
||||
host: '0.0.0.0',
|
||||
port: 8080,
|
||||
https: false,
|
||||
hotOnly: false,
|
||||
// See https://github.com/vuejs/vue-cli/blob/dev/docs/cli-service.md#configuring-proxy
|
||||
proxy: null, // string | Object
|
||||
before: app => {}
|
||||
},
|
||||
|
||||
// options for 3rd party plugins
|
||||
pluginOptions: {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## webpack
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
The easiest way to tweak the webpack config is provide an object to the `configureWebpack` option in `vue.config.js`:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
configureWebpack: {
|
||||
plugins: [
|
||||
new MyAwesomeWebpackPlugin()
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The object will be merged into the final webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
|
||||
|
||||
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
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
configureWebpack: config => {
|
||||
if (process.env.NODE_ENV === 'production') {
|
||||
// mutate config for production...
|
||||
} else {
|
||||
// mutate for development...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Chaining (Advanced)
|
||||
|
||||
The internal webpack config is maintained using [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). The library provides an abstraction over the raw webpack config, with the ability to define named loader rules and named plugins, and later "tap" into those rules and modify their options.
|
||||
|
||||
This allows us finer-grained control over the internal config. Here are some examples:
|
||||
|
||||
#### Transpiling a Dependency Module
|
||||
|
||||
By default the Babel configuration skips
|
||||
|
||||
``` 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')],
|
||||
})
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Replace existing Base Loader
|
||||
|
||||
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:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config.module
|
||||
.rule('svg')
|
||||
.use('file-loader')
|
||||
.loader('vue-svg-loader')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Modifying Plugin Options
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
.plugin('html')
|
||||
.tap(args => {
|
||||
return [/* new args to pass to html-webpack-plugin's constructor */]
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You will need to familiarize yourself with [webpack-chain's API](https://github.com/mozilla-neutrino/webpack-chain#getting-started) and [read some source code](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-service/lib/config) in order to understand how to leverage the full power of this option, but it gives you a more expressive and safer way to modify the webpack config than directly mutation values.
|
||||
|
||||
For example, say you want to change the default location of `index.html` from `/Users/username/proj/public/index.html` to `/Users/username/proj/app/templates/index.html`. By referencing [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin#options) you can see a list of options you can pass in. To change our template path we can pass in a new template path with the following config:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
.plugin('html')
|
||||
.tap(args => {
|
||||
args[0].template = '/Users/username/proj/app/templates/index.html'
|
||||
return args
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can confirm that this change has taken place by examining the vue webpack config with the `vue inspect` utility, which we will discuss next.
|
||||
|
||||
### Inspecting the Project's Webpack Config
|
||||
|
||||
Since `@vue/cli-service` abstracts away the webpack config, it may be more difficult to understand what is included in the config, especially when you are trying to make tweaks yourself.
|
||||
|
||||
`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:
|
||||
|
||||
``` bash
|
||||
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:
|
||||
|
||||
``` bash
|
||||
# only inspect the first rule
|
||||
vue inspect module.rules.0
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
<projectRoot>/node_modules/@vue/cli-service/webpack.config.js
|
||||
```
|
||||
|
||||
This file dynamically resolves and exports the exact same webpack config used in `vue-cli-service` commands, including those from plugins and even your custom configurations.
|
||||
|
||||
## CSS
|
||||
|
||||
Vue CLI projects comes with support for [PostCSS](http://postcss.org/), [CSS Modules](https://github.com/css-modules/css-modules) and pre-processors including [Sass](https://sass-lang.com/), [Less](http://lesscss.org/) and [Stylus](http://stylus-lang.com/).
|
||||
|
||||
### PostCSS
|
||||
|
||||
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).
|
||||
|
||||
### 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>`.
|
||||
|
||||
To import CSS or other pre-processor files as CSS Modules in JavaScript, the filename should end with `.module.(css|less|sass|scss|styl)`:
|
||||
|
||||
``` js
|
||||
import styles from './foo.module.css'
|
||||
// works for all supported pre-processors as well
|
||||
import sassStyles from './foo.module.scss'
|
||||
```
|
||||
|
||||
Alternatively, you can import a file explicitly with a `?module` resourceQuery so that you can drop the `.module` in the filename:
|
||||
|
||||
``` js
|
||||
import styles from './foo.css?module'
|
||||
// works for all supported pre-processors as well
|
||||
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`.
|
||||
|
||||
### Pre-Processors
|
||||
|
||||
You can select pre-processors (Sass/Less/Stylus) when creating the project. If you did not do so, you can also just manually install the corresponding webpack loaders. The loaders are pre-configured and will automatically be picked up. For example, to add Sass to an existing project, simply run:
|
||||
|
||||
``` bash
|
||||
npm install -D sass-loader node-sass
|
||||
```
|
||||
|
||||
Then you can import `.scss` files, or use it in `*.vue` files with:
|
||||
|
||||
``` vue
|
||||
<style lang="scss">
|
||||
$color = red;
|
||||
</style>
|
||||
```
|
||||
|
||||
### Passing Options to Pre-Processor Loaders
|
||||
|
||||
Sometimes you may want to pass options to the pre-processor's webpack loader. You can do that using the `css.loaderOptions` option in `vue.config.js`. For example, to pass some shared global variables to all your Sass styles:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
const fs = require('fs')
|
||||
|
||||
module.exports = {
|
||||
css: {
|
||||
loaderOptions: {
|
||||
sass: {
|
||||
data: fs.readFileSync('src/variables.scss', 'utf-8')
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
You can configure the dev server's behavior using the `devServer` option in `vue.config.js`:
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
devServer: {
|
||||
open: process.platform === 'darwin',
|
||||
host: '0.0.0.0',
|
||||
port: 8080,
|
||||
https: false,
|
||||
hotOnly: false,
|
||||
proxy: null, // string | Object
|
||||
before: app => {
|
||||
// app is an express instance
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In addition to these default values, [all options for `webpack-dev-server`](https://webpack.js.org/configuration/dev-server/) are also supported.
|
||||
|
||||
### Configuring Proxy
|
||||
|
||||
If your frontend app and the backend API server are not running on the same host, you will need to proxy API requests to the API server during development. This is configurable via the `devServer.proxy` option in `vue.config.js`.
|
||||
|
||||
`devServer.proxy` can be a string pointing to the development API server:
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
devServer: {
|
||||
proxy: 'http://localhost:4000'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This will tell the dev server to proxy any unknown requests (requests that did not match a static file) to `http://localhost:4000`.
|
||||
|
||||
If you want to have more control over the proxy behavior, you can also use an object with `path: options` pairs. Consult [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware#proxycontext-config) for full options:
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
devServer: {
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: '<url>',
|
||||
ws: true,
|
||||
changeOrigin: true
|
||||
},
|
||||
'/foo': {
|
||||
target: '<other_url>'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Babel
|
||||
|
||||
Babel can be configured via `.babelrc` or the `babel` field in `package.json`.
|
||||
|
||||
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.
|
||||
|
||||
## ESLint
|
||||
|
||||
ESLint can be configured via `.eslintrc` or `eslintConfig` field in `package.json`.
|
||||
|
||||
See [@vue/cli-plugin-eslint](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-eslint) for more details.
|
||||
|
||||
## TypeScript
|
||||
|
||||
TypeScript can be configured via `tsconfig.json`.
|
||||
|
||||
See [@vue/cli-plugin-typescript](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-typescript) for more details.
|
||||
|
||||
## Unit Testing
|
||||
|
||||
### Jest
|
||||
|
||||
See [@vue/cli-plugin-unit-jest](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-jest) for more details.
|
||||
|
||||
### Mocha (via `mocha-webpack`)
|
||||
|
||||
See [@vue/cli-plugin-unit-mocha](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-mocha) for more details.
|
||||
|
||||
## E2E Testing
|
||||
|
||||
### Cypress
|
||||
|
||||
See [@vue/cli-plugin-e2e-cypress](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-cypress) for more details.
|
||||
|
||||
### Nightwatch
|
||||
|
||||
See [@vue/cli-plugin-e2e-nightwatch](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch) for more details.
|
||||
69
docs/css.md
69
docs/css.md
@@ -1,69 +0,0 @@
|
||||
## CSS
|
||||
|
||||
- [PostCSS](#postcss)
|
||||
- [CSS Modules](#css-modules)
|
||||
- [Pre-Processors](#pre-processors)
|
||||
- [Passing Options to Pre-Processor Loaders](#passing-options-to-pre-processor-loaders)
|
||||
|
||||
### PostCSS
|
||||
|
||||
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).
|
||||
|
||||
### 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>`.
|
||||
|
||||
To import CSS or other pre-processor files as CSS Modules in JavaScript, the filename should end with `.module.(css|less|sass|scss|styl)`:
|
||||
|
||||
``` js
|
||||
import styles from './foo.module.css'
|
||||
// works for all supported pre-processors as well
|
||||
import sassStyles from './foo.module.scss'
|
||||
```
|
||||
|
||||
Alternatively, you can import a file explicitly with a `?module` resourceQuery so that you can drop the `.module` in the filename:
|
||||
|
||||
``` js
|
||||
import styles from './foo.css?module'
|
||||
// works for all supported pre-processors as well
|
||||
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`.
|
||||
|
||||
### Pre-Processors
|
||||
|
||||
You can select pre-processors (Sass/Less/Stylus) when creating the project. If you did not do so, you can also just manually install the corresponding webpack loaders. The loaders are pre-configured and will automatically be picked up. For example, to add Sass to an existing project, simply run:
|
||||
|
||||
``` sh
|
||||
npm install -D sass-loader node-sass
|
||||
```
|
||||
|
||||
Then you can import `.scss` files, or use it in `*.vue` files with:
|
||||
|
||||
``` vue
|
||||
<style lang="scss">
|
||||
$color = red;
|
||||
</style>
|
||||
```
|
||||
|
||||
### Passing Options to Pre-Processor Loaders
|
||||
|
||||
Sometimes you may want to pass options to the pre-processor's webpack loader. You can do that using the `css.loaderOptions` option in `vue.config.js`. For example, to pass some shared global variables to all your Sass styles:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
const fs = require('fs')
|
||||
|
||||
module.exports = {
|
||||
css: {
|
||||
loaderOptions: {
|
||||
sass: {
|
||||
data: fs.readFileSync('src/variables.scss', 'utf-8')
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is preferred over manually tapping into specific loaders, because these options will be shared across all rules that are related to it.
|
||||
@@ -1,14 +1,11 @@
|
||||
---
|
||||
sidebarDepth: 3
|
||||
---
|
||||
|
||||
# Plugin Development Guide
|
||||
|
||||
## Core Concepts
|
||||
|
||||
- [Creator](#creator)
|
||||
- [Service](#service)
|
||||
- [CLI Plugin](#cli-plugin)
|
||||
- [Service Plugin](#service-plugin)
|
||||
- [Generator](#generator)
|
||||
- [Prompts](#prompts)
|
||||
|
||||
There are two major parts of the system:
|
||||
|
||||
- `@vue/cli`: globally installed, exposes the `vue create <app>` command;
|
||||
@@ -281,7 +278,7 @@ module.exports = api => {
|
||||
|
||||
Alternatively, the user can skip the prompts and directly initialize the plugin by passing options via the command line, e.g.:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
vue invoke my-plugin --mode awesome
|
||||
```
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Localization
|
||||
# UI Localization
|
||||
|
||||
# Translate the UI
|
||||
## Translate the UI
|
||||
|
||||
Follow those simple steps to propose a new language for the CLI UI!
|
||||
|
||||
@@ -1,26 +1,7 @@
|
||||
# Plugin UI Development Guide
|
||||
# UI Plugin Development Guide
|
||||
|
||||
This guide will walk you through the development of cli-ui specific features for your vue-cli plugins.
|
||||
|
||||
- [Plugin Info](#plugin-info)
|
||||
- [Logo](#logo)
|
||||
- [Discoverability](#discoverability)
|
||||
- [UI API](#ui-api)
|
||||
- [UI files](#ui-files)
|
||||
- [Dev mode](#dev-mode)
|
||||
- [Project configurations](#project-configurations)
|
||||
- [Project tasks](#project-tasks)
|
||||
- [Prompts](#prompts)
|
||||
- [Client addon](#client-addon)
|
||||
- [Custom views](#custom-views)
|
||||
- [Shared data](#shared-data)
|
||||
- [Plugin actions](#plugin-actions)
|
||||
- [Inter-process communication (IPC)](#inter-process-communication-ipc)
|
||||
- [Local storage](#local-storage)
|
||||
- [Localization](#localization)
|
||||
- [Hooks](#hooks)
|
||||
- [Public static files](#public-static-files)
|
||||
|
||||
## Plugin Info
|
||||
|
||||
When used in the UI, your plugin can show additional information to make it more discoverable and recognizable.
|
||||
@@ -31,7 +12,7 @@ You can put a `logo.png` file in the root directory of the folder that will be p
|
||||
- When searching for a plugin to install
|
||||
- In the installed plugin list
|
||||
|
||||
|
||||
|
||||
|
||||
The logo should be a square non-transparent image (ideally 84x84).
|
||||
|
||||
@@ -61,13 +42,13 @@ You should add the url to the plugin website or repository in the `homepage` or
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## UI API
|
||||
|
||||
The cli-ui exposes an API that allows augmenting the project configurations and tasks, as well as sharing data and communicating with other processes.
|
||||
|
||||
|
||||
|
||||
|
||||
### UI files
|
||||
|
||||
@@ -93,7 +74,7 @@ vue ui --dev
|
||||
|
||||
### Project configurations
|
||||
|
||||
|
||||
|
||||
|
||||
You can add a project configuration with the `api.describeConfig` method.
|
||||
|
||||
@@ -239,7 +220,7 @@ api.describeConfig({
|
||||
|
||||
### Project tasks
|
||||
|
||||
|
||||
|
||||
|
||||
Tasks are generated from the `scripts` field in the project `package.json` file.
|
||||
|
||||
@@ -584,7 +565,7 @@ import WebpackDashboard from './components/WebpackDashboard.vue'
|
||||
ClientAddonApi.component('vue-webpack-dashboard', WebpackDashboard)
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
### Custom views
|
||||
|
||||
@@ -624,7 +605,7 @@ ClientAddonApi.addRoutes('vue-webpack', [
|
||||
])
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
### Shared data
|
||||
|
||||
@@ -900,7 +881,7 @@ locales.keys().forEach(key => {
|
||||
|
||||
#### Help translate the main UI!
|
||||
|
||||
See [how to help translating the main UI](./localization.md).
|
||||
See [how to help translating the main UI](./ui-localization.md).
|
||||
|
||||
### Hooks
|
||||
|
||||
56
docs/guide/README.md
Normal file
56
docs/guide/README.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
sidebarDepth: 1
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
Vue CLI is a full system for rapid Vue.js development, providing:
|
||||
|
||||
- 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.
|
||||
|
||||
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.
|
||||
|
||||
## Understanding the Architecture
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
See [CLI Service docs](./cli-service.md) for all available commands.
|
||||
|
||||
### CLI Plugins
|
||||
|
||||
Each project will likely contain a number of
|
||||
|
||||
### Presets
|
||||
|
||||
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.
|
||||
1
docs/guide/browser-compatibility.md
Normal file
1
docs/guide/browser-compatibility.md
Normal file
@@ -0,0 +1 @@
|
||||
# Browser Compatibility
|
||||
@@ -1,6 +1,6 @@
|
||||
## Build Targets
|
||||
# Build Targets
|
||||
|
||||
### App
|
||||
## App
|
||||
|
||||
App mode is the default mode. In this mode:
|
||||
|
||||
@@ -9,7 +9,7 @@ App mode is the default mode. In this mode:
|
||||
- static assets under 10kb are inlined into JavaScript
|
||||
- static assets in `public` are copied into output directory
|
||||
|
||||
### Library
|
||||
## Library
|
||||
|
||||
You can build a single entry as a library using
|
||||
|
||||
@@ -38,9 +38,27 @@ A lib build outputs:
|
||||
|
||||
- `dist/myLib.css`: Extracted CSS file (can be forced into inlined by setting `css: { extract: false }` in `vue.config.js`)
|
||||
|
||||
### Vue vs. JS/TS Entry Files
|
||||
|
||||
When using a `.vue` file as entry, your library will directly expose the Vue component itself, because the component is always the default export.
|
||||
|
||||
However, when you are using a `.js` or `.ts` file as your entry, it may contain named exports, so your library will be exposed as a Module. This means the default export of your library must be accessed as `window.yourLib.default` in UMD builds, or as `const myLib = require('mylib').default` in CommonJS builds. If you don't have any named exports and wish to directly expose the default export, you can use the following webpack configuration in `vue.config.js`:
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
configureWebpack: {
|
||||
output: {
|
||||
libraryExport: 'default'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Vue Externalization
|
||||
|
||||
**In lib mode, Vue is externalized.** This means the bundle will not bundle Vue even if your code imports Vue. If the lib is used via a bundler, it will attempt to load Vue as a dependency through the bundler; otherwise, it falls back to a global `Vue` variable.
|
||||
|
||||
### Web Component
|
||||
## Web Component
|
||||
|
||||
> [Compatibility](https://github.com/vuejs/vue-web-component-wrapper#compatibility)
|
||||
|
||||
@@ -64,7 +82,7 @@ This mode allows consumers of your component to use the Vue component as a norma
|
||||
<my-element></my-element>
|
||||
```
|
||||
|
||||
#### Bundle that Registers Multiple Web Components
|
||||
### Bundle that Registers Multiple Web Components
|
||||
|
||||
When building a web component bundle, you can also target multiple components by using a glob as entry:
|
||||
|
||||
@@ -76,8 +94,6 @@ When building multiple web components, `--name` will be used as the prefix and t
|
||||
|
||||
### Async Web Component
|
||||
|
||||
> [Compatibility](https://github.com/vuejs/vue-web-component-wrapper#compatibility)
|
||||
|
||||
When targeting multiple web components, the bundle may become quite large, and the user may only use a few of the components your bundle registers. The async web component mode produces a code-split bundle with a small entry file that provides the shared runtime between all the components, and registers all the custom elements upfront. The actual implementation of a component is then fetched on-demand only when an instance of the corresponding custom element is used on the page:
|
||||
|
||||
```
|
||||
@@ -104,3 +120,7 @@ Now on the page, the user only needs to include Vue and the entry file:
|
||||
<!-- foo-one's implementation chunk is auto fetched when it's used -->
|
||||
<foo-one></foo-one>
|
||||
```
|
||||
|
||||
### Vue Externalization
|
||||
|
||||
**In web component mode, Vue is externalized.** This means the bundle will not bundle Vue even if your code imports Vue. The bundle will assume `Vue` is available on the host page as a global variable.
|
||||
@@ -1,15 +1,6 @@
|
||||
## CLI Service
|
||||
# CLI Service
|
||||
|
||||
- [Using the Binary](#using-the-binary)
|
||||
- [serve](#serve)
|
||||
- [Configuring Proxy](#configuring-proxy)
|
||||
- [build](#build)
|
||||
- [Caching and Parallel Mode](#caching-and-parallel-mode)
|
||||
- [Building as Library or Web Component](#building-as-library-or-web-component)
|
||||
- [inspect](#inspect)
|
||||
- [Checking All Available Commands](#checking-all-available-commands)
|
||||
|
||||
### Using the Binary
|
||||
## Using the Binary
|
||||
|
||||
Inside a Vue CLI project, `@vue/cli-service` installs a binary named `vue-cli-service`. You can access the binary directly as `vue-cli-service` in npm scripts, or as `./node_modules/.bin/vue-cli-service` from the terminal.
|
||||
|
||||
@@ -24,7 +15,7 @@ This is what you will see in the `package.json` of a project using the default p
|
||||
}
|
||||
```
|
||||
|
||||
### serve
|
||||
## serve
|
||||
|
||||
```
|
||||
Usage: vue-cli-service serve [options]
|
||||
@@ -39,62 +30,7 @@ Options:
|
||||
--https use https (default: false)
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
You can configure the dev server's behavior using the `devServer` option in `vue.config.js`:
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
devServer: {
|
||||
open: process.platform === 'darwin',
|
||||
host: '0.0.0.0',
|
||||
port: 8080,
|
||||
https: false,
|
||||
hotOnly: false,
|
||||
proxy: null, // string | Object
|
||||
before: app => {
|
||||
// app is an express instance
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In addition to these default values, [all options for `webpack-dev-server`](https://webpack.js.org/configuration/dev-server/) are also supported.
|
||||
|
||||
#### Configuring Proxy
|
||||
|
||||
`devServer.proxy` can be a string pointing to the development API server:
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
devServer: {
|
||||
proxy: 'http://localhost:4000'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This will tell the dev server to proxy any unknown requests (requests that did not match a static file) to `http://localhost:4000`.
|
||||
|
||||
If you want to have more control over the proxy behavior, you can also use an object with `path: options` pairs. Consult [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware#proxycontext-config) for full options:
|
||||
|
||||
``` js
|
||||
module.exports = {
|
||||
devServer: {
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: '<url>',
|
||||
ws: true,
|
||||
changeOrigin: true
|
||||
},
|
||||
'/foo': {
|
||||
target: '<other_url>'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### build
|
||||
## build
|
||||
|
||||
```
|
||||
Usage: vue-cli-service build [options] [entry|pattern]
|
||||
@@ -110,16 +46,17 @@ 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
|
||||
### 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.
|
||||
|
||||
- `cache-loader` is enabled for Babel/TypeScript transpilation by default.
|
||||
- `thread-loader` will be enabled for Babel/TypeScript transpilation when the machine has more than 1 CPU cores.
|
||||
|
||||
#### Building as Library or Web Components
|
||||
## 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
|
||||
## inspect
|
||||
|
||||
```
|
||||
Usage: vue-cli-service inspect [options] [...paths]
|
||||
@@ -129,18 +66,20 @@ 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](./webpack.md#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/webpack.md#inspecting-the-projects-webpack-config) for more details.
|
||||
|
||||
### Checking All Available Commands
|
||||
## 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:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
./node_modules/.bin/vue-cli-service help
|
||||
```
|
||||
|
||||
You can also learn about the available options of each command with:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
./node_modules/.bin/vue-cli-service help [command]
|
||||
```
|
||||
|
||||
## Git Hooks
|
||||
@@ -1,23 +1,13 @@
|
||||
## CLI
|
||||
# Creating a Project
|
||||
|
||||
- [Installation](#installation)
|
||||
- [Usage](#usage)
|
||||
- [Launch the GUI](#launch-the-gui)
|
||||
- [Creating a New Project](#creating-a-new-project)
|
||||
- [Presets](#presets)
|
||||
- [Zero-config Prototyping](#zero-config-prototyping)
|
||||
- [Installing Plugins in an Existing Project](#installing-plugins-in-an-existing-project)
|
||||
- [Inspecting the webpack Config](#inspecting-the-projects-webpack-config)
|
||||
- [Pulling 2.x Templates](#pulling-vue-cli2x-templates-legacy)
|
||||
## Installation
|
||||
|
||||
### Installation
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
npm install -g @vue/cli
|
||||
vue create my-project
|
||||
```
|
||||
|
||||
### Usage
|
||||
## Commands
|
||||
|
||||
```
|
||||
Usage: vue <command> [options]
|
||||
@@ -35,23 +25,7 @@ Commands:
|
||||
|
||||
For each command, you can also use `vue <command> --help` to see more detailed usage.
|
||||
|
||||
### Launch the GUI
|
||||
|
||||
```
|
||||
Usage: ui [options]
|
||||
|
||||
start and open the vue-cli ui
|
||||
|
||||
|
||||
Options:
|
||||
|
||||
-p, --port <port> Port used for the UI server (by default search for available port)
|
||||
-h, --help output usage information
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Creating a New Project
|
||||
## Creating a New Project
|
||||
|
||||
```
|
||||
Usage: create [options] <app-name>
|
||||
@@ -66,14 +40,14 @@ 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] Force / skip git intialization, optionally specify initial commit message
|
||||
-g, --git [message|false] Force / skip git intialization, 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
|
||||
-h, --help output usage information
|
||||
```
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
vue create my-project
|
||||
```
|
||||
|
||||
@@ -81,7 +55,29 @@ vue create my-project
|
||||
<img width="682px" src="https://raw.githubusercontent.com/vuejs/vue-cli/dev/docs/screenshot.png">
|
||||
</p>
|
||||
|
||||
### Presets
|
||||
## Launch the GUI
|
||||
|
||||
You can also create and manage projects using a graphical interface with the `vue ui` command.
|
||||
|
||||
```
|
||||
Usage: ui [options]
|
||||
|
||||
start and open the vue-cli ui
|
||||
|
||||
|
||||
Options:
|
||||
|
||||
-p, --port <port> Port used for the UI server (by default search for available port)
|
||||
-h, --help output usage information
|
||||
```
|
||||
|
||||
``` bash
|
||||
vue ui
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Presets
|
||||
|
||||
After you've selected features, you can optionally save it as a preset so that you can reuse it for future projects. If you want to delete or tweak a saved preset, you can do that by editing `~/.vuerc`.
|
||||
|
||||
@@ -120,7 +116,7 @@ The preset data is used by plugin generators to generate corresponding project f
|
||||
|
||||
These additional configurations will be merged into `package.json` or corresponding config files, depending on the value of `useConfigFiles`. For example, with `"useConfigFiles": true`, the value of `configs.vue` will be merged into `vue.config.js`.
|
||||
|
||||
#### Preset Plugin Versioning
|
||||
### Preset Plugin Versioning
|
||||
|
||||
You can explicitly specify versions of the plugins being used:
|
||||
|
||||
@@ -137,33 +133,33 @@ You can explicitly specify versions of the plugins being used:
|
||||
|
||||
Note this is not required for official plugins - when omitted, the CLI will automatically use the latest version available in the registry. However, **it is recommended to provide a explicit version range for any 3rd party plugins listed in a preset**.
|
||||
|
||||
#### Remote Presets
|
||||
### Remote Presets
|
||||
|
||||
You can share a preset with other developers by publishing it in a git repo. The repo should contain a `preset.json` file containing the preset data. You can then use the `--preset` option to use the remote preset when creating a project:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
# use preset from GitHub repo
|
||||
vue create --preset username/repo my-project
|
||||
```
|
||||
|
||||
GitLab and BitBucket are also supported. Make sure to use the `--clone` option if fetching from private repos:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
vue create --preset gitlab:username/repo --clone my-project
|
||||
vue create --preset bitbucket:username/repo --clone my-project
|
||||
```
|
||||
|
||||
### Zero-config Prototyping
|
||||
## Zero-config Prototyping
|
||||
|
||||
You can rapidly prototype with just a single `*.vue` file with the `vue serve` and `vue build` commands, but they require an additional global addon to be installed first:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
npm install -g @vue/cli-service-global
|
||||
```
|
||||
|
||||
The drawback of `vue serve` is that it relies on globally installed dependencies which may be inconsistent on different machines. Therefore this is only recommended for rapid prototyping.
|
||||
|
||||
#### vue serve
|
||||
### vue serve
|
||||
|
||||
```
|
||||
Usage: serve [options] [entry]
|
||||
@@ -180,20 +176,20 @@ Options:
|
||||
|
||||
All you need is a `*.vue` file:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
echo '<template><h1>Hello!</h1></template>' > App.vue
|
||||
vue serve
|
||||
```
|
||||
|
||||
`vue serve` uses the same default setup (webpack, babel, postcss & eslint) as projects created by `vue create`. It automatically infers the entry file in the current directory - the entry can be one of `main.js`, `index.js`, `App.vue` or `app.vue`. You can also explicitly specify the entry file:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
vue serve MyComponent.vue
|
||||
```
|
||||
|
||||
If needed, you can also provide an `index.html`, `package.json`, install and use local dependencies, or even configure babel, postcss & eslint with corresponding config files.
|
||||
|
||||
#### vue build
|
||||
### vue build
|
||||
|
||||
```
|
||||
Usage: build [options] [entry]
|
||||
@@ -211,17 +207,15 @@ Options:
|
||||
|
||||
You can also build the target file into a production bundle for deployment with `vue build`:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
vue build MyComponent.vue
|
||||
```
|
||||
|
||||
`vue build` also provides the ability to build the component as a library or a web component. See [Build Targets](./build-targets.md) for more details.
|
||||
|
||||
### Installing Plugins in an Existing Project
|
||||
## Installing Plugins in an Existing Project
|
||||
|
||||
Each CLI plugin ships with a generator (which creates files) and a runtime plugin (which tweaks the core webpack config and injects commands). When you use `vue create` to create a new project, some plugins will be pre-installed for you based on your feature selection. In case you want to install a plugin into an already created project, you can do so with the `vue add` command:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
vue add @vue/eslint
|
||||
```
|
||||
|
||||
@@ -229,41 +223,41 @@ vue add @vue/eslint
|
||||
|
||||
The command resolves `@vue/eslint` to the full package name `@vue/cli-plugin-eslint`, installs it from npm, and invokes its generator.
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
# these are equivalent to the previous usage
|
||||
vue add @vue/cli-plugin-eslint
|
||||
```
|
||||
|
||||
Without the `@vue` prefix, the command will resolve to an unscoped package instead. For example, to install the 3rd party plugin `vue-cli-plugin-apollo`:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
# installs and invokes vue-cli-plugin-apollo
|
||||
vue add apollo
|
||||
```
|
||||
|
||||
You can also use 3rd party plugins under a specific scope. For example, if a plugin is named `@foo/vue-cli-plugin-bar`, you can add it with:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
vue add @foo/bar
|
||||
```
|
||||
|
||||
Finally, you can pass generator options to the installed plugin:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
vue add @vue/eslint --config airbnb --lintOn save
|
||||
```
|
||||
|
||||
If a plugin is already installed, you can skip the installation and only invoke its generator with the `vue invoke` command. The command takes the same arguments as `vue add`.
|
||||
|
||||
### Inspecting the Project's Webpack Config
|
||||
## Inspecting the Project's Webpack Config
|
||||
|
||||
You can use `vue inspect` to inspect the webpack config inside a Vue CLI project. See [Inspecting Webpack Config](./webpack.md#inspecting-the-projects-webpack-config) for more details.
|
||||
You can use `vue inspect` to inspect the webpack config inside a Vue CLI project. See [Inspecting Webpack Config](../config/webpack.md#inspecting-the-projects-webpack-config) for more details.
|
||||
|
||||
### Pulling `vue-cli@2.x` Templates (Legacy)
|
||||
## Pulling `vue-cli@2.x` Templates (Legacy)
|
||||
|
||||
`@vue/cli` uses the same `vue` binary, so it overwrites `vue-cli@2.x`. If you still need the legacy `vue init` functionality, you can install a global bridge:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
npm install -g @vue/cli-init
|
||||
# vue init now works exactly the same as vue-cli@2.x
|
||||
vue init webpack my-project
|
||||
1
docs/guide/deployment.md
Normal file
1
docs/guide/deployment.md
Normal file
@@ -0,0 +1 @@
|
||||
# Deployment
|
||||
@@ -1,9 +1,24 @@
|
||||
## Static Asset Handling
|
||||
# HTML and Static Assets
|
||||
|
||||
- [Relative Path Imports](#relative-path-imports)
|
||||
- [URL Transform Rules](#url-transform-rules)
|
||||
- [The `public` Folder](#the-public-folder)
|
||||
- [When to use the `public` folder](#when-to-use-the-public-folder)
|
||||
## Understanding `baseUrl`
|
||||
|
||||
## HTML
|
||||
|
||||
### The Index File
|
||||
|
||||
The file `public/index.html` is a template that will be processed with [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin). During build, asset links will be injected automatically. In addition, Vue CLI also automatically injects resource hints (`preload/prefetch`), manifest/icon links (when PWA plugin is used) and inlines the webpack runtime / chunk manifest for optimal performance.
|
||||
|
||||
### Prefetch & Preload
|
||||
|
||||
### Building a Multi-Page App
|
||||
|
||||
## Static Assets Handling
|
||||
|
||||
Static assets can be handled in two different ways:
|
||||
|
||||
- Imported in JavaScript or referenced in templates/CSS via relative paths. Such references will be handled by webpack.
|
||||
|
||||
- Placed in the `public` directory and referenced via absolute paths. These assets will simply be copied and not go through webpack.
|
||||
|
||||
### Relative Path Imports
|
||||
|
||||
@@ -12,18 +27,18 @@ When you reference a static asset using relative path inside JavaScript, CSS or
|
||||
For example, `url(./image.png)` will be translated into `require('./image.png')`, and
|
||||
|
||||
``` html
|
||||
<img src="../image.png">
|
||||
<img src="./image.png">
|
||||
```
|
||||
|
||||
will be compiled into:
|
||||
|
||||
``` js
|
||||
createElement('img', { attrs: { src: require('../image.png') }})
|
||||
createElement('img', { attrs: { src: require('./image.png') }})
|
||||
```
|
||||
|
||||
Internally, we use `file-loader` to determine the final file location with version hashes and correct public base paths, and use `url-loader` to conditionally inline assets that are smaller than 10kb, reducing the amount of HTTP requests.
|
||||
|
||||
#### URL Transform Rules
|
||||
### URL Transform Rules
|
||||
|
||||
- If the URL is an absolute path (e.g. `/images/foo.png`), it will be preserved as-is.
|
||||
|
||||
@@ -71,7 +86,7 @@ The `public` directory is provided as an **escape hatch**, and when you referenc
|
||||
<img :src="`${baseUrl}my-image.png`">
|
||||
```
|
||||
|
||||
#### When to use the `public` folder
|
||||
### When to use the `public` folder
|
||||
|
||||
- You need a file with a specific name in the build output.
|
||||
- You have thousands of images and need to dynamically reference their paths.
|
||||
@@ -1,15 +1,8 @@
|
||||
## Environment Variables and Modes
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Modes](#modes)
|
||||
- [Using Env Variables in Client-side Code](#using-env-variables-in-client-side-code)
|
||||
- [Local Only Variables](#local-only-variables)
|
||||
|
||||
### Overview
|
||||
# Environment Variables and Modes
|
||||
|
||||
You can specify env variables by placing the following files in your project root:
|
||||
|
||||
``` sh
|
||||
``` bash
|
||||
.env # loaded in all cases
|
||||
.env.local # loaded in all cases, ignored by git
|
||||
.env.[mode] # only loaded in specified mode
|
||||
@@ -25,7 +18,7 @@ VUE_APP_SECRET=secret
|
||||
|
||||
Loaded variables will become available to all `vue-cli-service` commands, plugins and dependencies.
|
||||
|
||||
### Modes
|
||||
## Modes
|
||||
|
||||
**Mode** is an important concept in Vue CLI projects. By default, there are three modes in a Vue CLI project:
|
||||
|
||||
@@ -43,7 +36,7 @@ You can overwrite the default mode used for a command by passing the `--mode` op
|
||||
"dev-build": "vue-cli-service build --mode development",
|
||||
```
|
||||
|
||||
### Using Env Variables in Client-side Code
|
||||
## Using Env Variables in Client-side Code
|
||||
|
||||
Only variables that start with `VUE_APP_` will be statically embedded into the client bundle with `webpack.DefinePlugin`. You can access them in your application code:
|
||||
|
||||
@@ -58,7 +51,7 @@ In addition to `VUE_APP_*` variables, there are also two special variables that
|
||||
- `NODE_ENV` - this will be one of `"development"`, `"production"` or `"test"` depending on the [mode](#modes) the app is running in.
|
||||
- `BASE_URL` - this corresponds to the `baseUrl` option in `vue.config.js` and is the base path your app is deployed at.
|
||||
|
||||
### Env Variables in Index HTML
|
||||
## Env Variables in Index HTML
|
||||
|
||||
All resolved env variables will be available inside `public/index.html` via [lodash template interpolation](https://lodash.com/docs/4.17.5#template):
|
||||
|
||||
@@ -72,7 +65,7 @@ For example, to reference static assets copied from the root of `public`, you wi
|
||||
<link rel="shortcut icon" href="<%= BASE_URL %>favicon.ico">
|
||||
```
|
||||
|
||||
### Local Only Variables
|
||||
## Local Only Variables
|
||||
|
||||
Sometimes you might have env variables that should not be committed into the codebase, especially if your project is hosted in a public repository. In that case you should use an `.env.local` file instead. Local env files are ignored in `.gitignore` by default.
|
||||
|
||||
1
docs/guide/plugins-and-presets.md
Normal file
1
docs/guide/plugins-and-presets.md
Normal file
@@ -0,0 +1 @@
|
||||
# Plugins and Presets
|
||||
1
docs/guide/prototyping.md
Normal file
1
docs/guide/prototyping.md
Normal file
@@ -0,0 +1 @@
|
||||
# Instant Prototyping
|
||||
1
docs/guide/ui.md
Normal file
1
docs/guide/ui.md
Normal file
@@ -0,0 +1 @@
|
||||
# Using the GUI
|
||||
160
docs/webpack.md
160
docs/webpack.md
@@ -1,160 +0,0 @@
|
||||
## Configuring webpack
|
||||
|
||||
- [Basic Configuration](#basic-configuration)
|
||||
- [Chaining](#chaining-advanced)
|
||||
- [Inspecting the Config](#inspecting-the-projects-webpack-config)
|
||||
- [Using Resolved Config as a File](#using-resolved-config-as-a-file)
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
The easiest way to tweak the webpack config is provide an object to the `configureWebpack` option in `vue.config.js`:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
configureWebpack: {
|
||||
plugins: [
|
||||
new MyAwesomeWebpackPlugin()
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The object will be merged into the final webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
|
||||
|
||||
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
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
configureWebpack: config => {
|
||||
if (process.env.NODE_ENV === 'production') {
|
||||
// mutate config for production...
|
||||
} else {
|
||||
// mutate for development...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Chaining (Advanced)
|
||||
|
||||
The internal webpack config is maintained using [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). The library provides an abstraction over the raw webpack config, with the ability to define named loader rules and named plugins, and later "tap" into those rules and modify their options.
|
||||
|
||||
This allows us finer-grained control over the internal config. Here are some examples:
|
||||
|
||||
#### Transpiling a Dependency Module
|
||||
|
||||
By default the Babel configuration skips
|
||||
|
||||
``` 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')],
|
||||
})
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Replace existing Base Loader
|
||||
|
||||
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:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config.module
|
||||
.rule('svg')
|
||||
.use('file-loader')
|
||||
.loader('vue-svg-loader')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Modifying Plugin Options
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
.plugin('html')
|
||||
.tap(args => {
|
||||
return [/* new args to pass to html-webpack-plugin's constructor */]
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You will need to familiarize yourself with [webpack-chain's API](https://github.com/mozilla-neutrino/webpack-chain#getting-started) and [read some source code](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-service/lib/config) in order to understand how to leverage the full power of this option, but it gives you a more expressive and safer way to modify the webpack config than directly mutation values.
|
||||
|
||||
For example, say you want to change the default location of `index.html` from `/Users/username/proj/public/index.html` to `/Users/username/proj/app/templates/index.html`. By referencing [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin#options) you can see a list of options you can pass in. To change our template path we can pass in a new template path with the following config:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
.plugin('html')
|
||||
.tap(args => {
|
||||
args[0].template = '/Users/username/proj/app/templates/index.html'
|
||||
return args
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can confirm that this change has taken place by examining the vue webpack config with the `vue inspect` utility, which we will discuss next.
|
||||
|
||||
### Inspecting the Project's Webpack Config
|
||||
|
||||
Since `@vue/cli-service` abstracts away the webpack config, it may be more difficult to understand what is included in the config, especially when you are trying to make tweaks yourself.
|
||||
|
||||
`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:
|
||||
|
||||
``` sh
|
||||
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:
|
||||
|
||||
``` sh
|
||||
# only inspect the first rule
|
||||
vue inspect module.rules.0
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
<projectRoot>/node_modules/@vue/cli-service/webpack.config.js
|
||||
```
|
||||
|
||||
This file dynamically resolves and exports the exact same webpack config used in `vue-cli-service` commands, including those from plugins and even your custom configurations.
|
||||
Reference in New Issue
Block a user