mirror of
https://github.com/vuejs/vue-cli.git
synced 2026-04-22 12:28:44 -05:00
docs: wip
This commit is contained in:
Evan You
@@ -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.
|
||||
@@ -0,0 +1 @@
|
||||
# Browser Compatibility
|
||||
@@ -0,0 +1,126 @@
|
||||
# Build Targets
|
||||
|
||||
## App
|
||||
|
||||
App mode is the default mode. In this mode:
|
||||
|
||||
- `index.html` with asset and resource hints injection
|
||||
- vendor libraries split into a separate chunk for better caching
|
||||
- static assets under 10kb are inlined into JavaScript
|
||||
- static assets in `public` are copied into output directory
|
||||
|
||||
## Library
|
||||
|
||||
You can build a single entry as a library using
|
||||
|
||||
```
|
||||
vue-cli-service build --target lib --name myLib [entry]
|
||||
```
|
||||
|
||||
```
|
||||
File Size Gzipped
|
||||
|
||||
dist/myLib.umd.min.js 13.28 kb 8.42 kb
|
||||
dist/myLib.umd.js 20.95 kb 10.22 kb
|
||||
dist/myLib.common.js 20.57 kb 10.09 kb
|
||||
dist/myLib.css 0.33 kb 0.23 kb
|
||||
```
|
||||
|
||||
The entry can be either a `.js` or a `.vue` file. If no entry is specified, `src/App.vue` will be used.
|
||||
|
||||
A lib build outputs:
|
||||
|
||||
- `dist/myLib.common.js`: A CommonJS bundle for consuming via bundlers (unfortunately, webpack currently does not support ES modules output format for bundles yet)
|
||||
|
||||
- `dist/myLib.umd.js`: A UMD bundle for consuming directly in browsers or with AMD loaders
|
||||
|
||||
- `dist/myLib.umd.min.js`: Minified version of the UMD build.
|
||||
|
||||
- `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
|
||||
|
||||
> [Compatibility](https://github.com/vuejs/vue-web-component-wrapper#compatibility)
|
||||
|
||||
You can build a single entry as a library using
|
||||
|
||||
```
|
||||
vue-cli-service build --target wc --name my-element [entry]
|
||||
```
|
||||
|
||||
This will produce a single JavaScript file (and its minified version) with everything inlined. The script, when included on a page, registers the `<my-element>` custom element, which wraps the target Vue component using `@vue/web-component-wrapper`. The wrapper automatically proxies properties, attributes, events and slots. See the [docs for `@vue/web-component-wrapper`](https://github.com/vuejs/vue-web-component-wrapper) for more details.
|
||||
|
||||
**Note the bundle relies on `Vue` being globally available on the page.**
|
||||
|
||||
This mode allows consumers of your component to use the Vue component as a normal DOM element:
|
||||
|
||||
``` html
|
||||
<script src="https://unpkg.com/vue"></script>
|
||||
<script src="path/to/my-element.js"></script>
|
||||
|
||||
<!-- use in plain HTML, or in any other framework -->
|
||||
<my-element></my-element>
|
||||
```
|
||||
|
||||
### Bundle that Registers Multiple Web Components
|
||||
|
||||
When building a web component bundle, you can also target multiple components by using a glob as entry:
|
||||
|
||||
```
|
||||
vue-cli-service build --target wc --name foo 'src/components/*.vue'
|
||||
```
|
||||
|
||||
When building multiple web components, `--name` will be used as the prefix and the custom element name will be inferred from the component filename. For example, with `--name foo` and a component named `HelloWorld.vue`, the resulting custom element will be registered as `<foo-hello-world>`.
|
||||
|
||||
### Async Web Component
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
vue-cli-service build --target wc-async --name foo 'src/components/*.vue'
|
||||
```
|
||||
|
||||
```
|
||||
File Size Gzipped
|
||||
|
||||
dist/foo.0.min.js 12.80 kb 8.09 kb
|
||||
dist/foo.min.js 7.45 kb 3.17 kb
|
||||
dist/foo.1.min.js 2.91 kb 1.02 kb
|
||||
dist/foo.js 22.51 kb 6.67 kb
|
||||
dist/foo.0.js 17.27 kb 8.83 kb
|
||||
dist/foo.1.js 5.24 kb 1.64 kb
|
||||
```
|
||||
|
||||
Now on the page, the user only needs to include Vue and the entry file:
|
||||
|
||||
``` html
|
||||
<script src="https://unpkg.com/vue"></script>
|
||||
<script src="path/to/foo.min.js"></script>
|
||||
|
||||
<!-- 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.
|
||||
@@ -0,0 +1,85 @@
|
||||
# CLI Service
|
||||
|
||||
## 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.
|
||||
|
||||
This is what you will see in the `package.json` of a project using the default preset:
|
||||
|
||||
``` json
|
||||
{
|
||||
"scripts": {
|
||||
"serve": "vue-cli-service serve --open",
|
||||
"build": "vue-cli-service build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## serve
|
||||
|
||||
```
|
||||
Usage: vue-cli-service serve [options]
|
||||
|
||||
Options:
|
||||
|
||||
--open open browser on server start
|
||||
--copy copy url to clipboard on server start
|
||||
--mode specify env mode (default: development)
|
||||
--host specify host (default: 0.0.0.0)
|
||||
--port specify port (default: 8080)
|
||||
--https use https (default: false)
|
||||
```
|
||||
|
||||
## build
|
||||
|
||||
```
|
||||
Usage: vue-cli-service build [options] [entry|pattern]
|
||||
|
||||
Options:
|
||||
|
||||
--mode specify env mode (default: production)
|
||||
--dest specify output directory (default: dist)
|
||||
--target app | lib | wc | wc-async (default: app)
|
||||
--name name for lib or web-component mode (default: "name" in package.json or entry filename)
|
||||
--watch watch for changes
|
||||
```
|
||||
|
||||
`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
|
||||
|
||||
```
|
||||
Usage: vue-cli-service inspect [options] [...paths]
|
||||
|
||||
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/webpack.md#inspecting-the-projects-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
|
||||
```
|
||||
|
||||
You can also learn about the available options of each command with:
|
||||
|
||||
``` bash
|
||||
./node_modules/.bin/vue-cli-service help [command]
|
||||
```
|
||||
|
||||
## Git Hooks
|
||||
@@ -0,0 +1,264 @@
|
||||
# Creating a Project
|
||||
|
||||
## Installation
|
||||
|
||||
``` bash
|
||||
npm install -g @vue/cli
|
||||
vue create my-project
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
```
|
||||
Usage: vue <command> [options]
|
||||
|
||||
Commands:
|
||||
|
||||
create [options] <app-name> create a new project powered by vue-cli-service
|
||||
invoke <plugin> [pluginOptions] invoke the generator of a plugin in an already created project
|
||||
inspect [options] [paths...] inspect the webpack config in a project with vue-cli-service
|
||||
serve [options] [entry] serve a .js or .vue file in development mode with zero config
|
||||
build [options] [entry] build a .js or .vue file in production mode with zero config
|
||||
ui [options] start and open the vue-cli ui
|
||||
init <template> <app-name> generate a project from a remote template (legacy API, requires @vue/cli-init)
|
||||
```
|
||||
|
||||
For each command, you can also use `vue <command> --help` to see more detailed usage.
|
||||
|
||||
## Creating a New Project
|
||||
|
||||
```
|
||||
Usage: create [options] <app-name>
|
||||
|
||||
create a new project powered by vue-cli-service
|
||||
|
||||
|
||||
Options:
|
||||
|
||||
-p, --preset <presetName> Skip prompts and use saved or remote preset
|
||||
-d, --default Skip prompts and use default preset
|
||||
-i, --inlinePreset <json> Skip prompts and use inline JSON string as preset
|
||||
-m, --packageManager <command> Use specified npm client when installing dependencies
|
||||
-r, --registry <url> Use specified npm registry when installing dependencies (only for npm)
|
||||
-g, --git [message|false] Force / skip git intialization, optionally specify initial commit message
|
||||
-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
|
||||
```
|
||||
|
||||
``` bash
|
||||
vue create my-project
|
||||
```
|
||||
|
||||
<p align="center">
|
||||
<img width="682px" src="https://raw.githubusercontent.com/vuejs/vue-cli/dev/docs/screenshot.png">
|
||||
</p>
|
||||
|
||||
## 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`.
|
||||
|
||||
A preset is defined in JSON. If you have saved a preset via the command line and then open `~/.vuerc`, you will find something like the following:
|
||||
|
||||
``` json
|
||||
{
|
||||
"useConfigFiles": true,
|
||||
"router": true,
|
||||
"vuex": true,
|
||||
"cssPreprocessor": "sass",
|
||||
"plugins": {
|
||||
"@vue/cli-plugin-babel": {},
|
||||
"@vue/cli-plugin-eslint": {
|
||||
"config": "airbnb",
|
||||
"lintOn": ["save", "commit"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The preset data is used by plugin generators to generate corresponding project files. In addition to the above fields, you can also add additional configuration for integrated tools:
|
||||
|
||||
``` js
|
||||
{
|
||||
"useConfigFiles": true,
|
||||
"plugins": {...},
|
||||
"configs": {
|
||||
"vue": {...},
|
||||
"postcss": {...},
|
||||
"eslintConfig": {...},
|
||||
"jest": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
You can explicitly specify versions of the plugins being used:
|
||||
|
||||
``` js
|
||||
{
|
||||
"plugins": {
|
||||
"@vue/cli-plugin-eslint": {
|
||||
"version": "^3.0.0",
|
||||
// ... other options for this plugin
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
``` 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:
|
||||
|
||||
``` bash
|
||||
vue create --preset gitlab:username/repo --clone my-project
|
||||
vue create --preset bitbucket:username/repo --clone my-project
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
``` 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
|
||||
|
||||
```
|
||||
Usage: serve [options] [entry]
|
||||
|
||||
serve a .js or .vue file in development mode with zero config
|
||||
|
||||
|
||||
Options:
|
||||
|
||||
-o, --open Open browser
|
||||
-c, --copy Copy local url to clipboard
|
||||
-h, --help output usage information
|
||||
```
|
||||
|
||||
All you need is a `*.vue` file:
|
||||
|
||||
``` 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:
|
||||
|
||||
``` 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
|
||||
|
||||
```
|
||||
Usage: build [options] [entry]
|
||||
|
||||
build a .js or .vue file in production mode with zero config
|
||||
|
||||
|
||||
Options:
|
||||
|
||||
-t, --target <target> Build target (app | lib | wc | wc-async, default: app)
|
||||
-n, --name <name> name for lib or web-component (default: entry filename)
|
||||
-d, --dest <dir> output directory (default: dist)
|
||||
-h, --help output usage information
|
||||
```
|
||||
|
||||
You can also build the target file into a production bundle for deployment with `vue build`:
|
||||
|
||||
``` bash
|
||||
vue build MyComponent.vue
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
``` bash
|
||||
vue add @vue/eslint
|
||||
```
|
||||
|
||||
> Note: it is recommended to commit your project's current state before running `vue add`, since the command will invoke the plugin's file generator and potentially make changes to your existing files.
|
||||
|
||||
The command resolves `@vue/eslint` to the full package name `@vue/cli-plugin-eslint`, installs it from npm, and invokes its generator.
|
||||
|
||||
``` 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`:
|
||||
|
||||
``` 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:
|
||||
|
||||
``` bash
|
||||
vue add @foo/bar
|
||||
```
|
||||
|
||||
Finally, you can pass generator options to the installed plugin:
|
||||
|
||||
``` 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
|
||||
|
||||
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)
|
||||
|
||||
`@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:
|
||||
|
||||
``` bash
|
||||
npm install -g @vue/cli-init
|
||||
# vue init now works exactly the same as vue-cli@2.x
|
||||
vue init webpack my-project
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
# Deployment
|
||||
@@ -0,0 +1,93 @@
|
||||
# HTML and Static Assets
|
||||
|
||||
## 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
|
||||
|
||||
When you reference a static asset using relative path inside JavaScript, CSS or `*.vue` files, the asset will be included into webpack's dependency graph. During this compilation process, all asset URLs such as `<img src="...">`, `background: url(...)` and CSS `@import` are **resolved as module dependencies**.
|
||||
|
||||
For example, `url(./image.png)` will be translated into `require('./image.png')`, and
|
||||
|
||||
``` html
|
||||
<img src="./image.png">
|
||||
```
|
||||
|
||||
will be compiled into:
|
||||
|
||||
``` js
|
||||
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
|
||||
|
||||
- If the URL is an absolute path (e.g. `/images/foo.png`), it will be preserved as-is.
|
||||
|
||||
- If the URL starts with `.`, it's interpreted as a relative module request and resolved based on the folder structure on your file system.
|
||||
|
||||
- If the URL starts with `~`, anything after it is interpreted as a module request. This means you can even reference assets inside node modules:
|
||||
|
||||
``` html
|
||||
<img src="~/some-npm-package/foo.png">
|
||||
```
|
||||
|
||||
- If the URL starts with `@`, it's also interpreted as a module request. This is useful because Vue CLI by default aliases `@` to `<projectRoot>/src`.
|
||||
|
||||
### The `public` Folder
|
||||
|
||||
Any static assets placed in the `public` folder will simply be copied and not go through webpack. You need to reference to them using absolute paths.
|
||||
|
||||
Note we recommended importing assets as part of your module dependency graph so that they will go through webpack with the following benefits:
|
||||
|
||||
- Scripts and stylesheets get minified and bundled together to avoid extra network requests.
|
||||
- Missing files cause compilation errors instead of 404 errors for your users.
|
||||
- Result filenames include content hashes so you don’t need to worry about browsers caching their old versions.
|
||||
|
||||
The `public` directory is provided as an **escape hatch**, and when you reference it via absolute path, you need to take into account where your app will be deployed. If your app is not deployed at the root of a domain, you will need to prefix your URLs with the base path:
|
||||
|
||||
- In `public/index.html`, you need to prefix the link with `<%= webpackConfig.output.publicPath %>`:
|
||||
|
||||
``` html
|
||||
<link rel="shortcut icon" href="<%= webpackConfig.output.publicPath %>favicon.ico">
|
||||
```
|
||||
|
||||
- In templates, you will need to first pass the base URL to your component:
|
||||
|
||||
``` js
|
||||
data () {
|
||||
return {
|
||||
baseUrl: process.env.BASE_URL
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
``` html
|
||||
<img :src="`${baseUrl}my-image.png`">
|
||||
```
|
||||
|
||||
### 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.
|
||||
- Some library may be incompatible with Webpack and you have no other option but to include it as a `<script>` tag.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Environment Variables and Modes
|
||||
|
||||
You can specify env variables by placing the following files in your project root:
|
||||
|
||||
``` bash
|
||||
.env # loaded in all cases
|
||||
.env.local # loaded in all cases, ignored by git
|
||||
.env.[mode] # only loaded in specified mode
|
||||
.env.[mode].local # only loaded in specified mode, ignored by git
|
||||
```
|
||||
|
||||
An env file simply contains key=value pairs of environment variables:
|
||||
|
||||
```
|
||||
FOO=bar
|
||||
VUE_APP_SECRET=secret
|
||||
```
|
||||
|
||||
Loaded variables will become available to all `vue-cli-service` commands, plugins and dependencies.
|
||||
|
||||
## Modes
|
||||
|
||||
**Mode** is an important concept in Vue CLI projects. By default, there are three modes in a Vue CLI project:
|
||||
|
||||
- `development` is used by `vue-cli-service serve`
|
||||
- `production` is used by `vue-cli-service build` and `vue-cli-service test:e2e`
|
||||
- `test` is used by `vue-cli-service test:unit`
|
||||
|
||||
Note that a mode is different from `NODE_ENV`, as a mode can contain multiple environment variables. That said, each mode does set `NODE_ENV` to the same value by default - for example, `NODE_ENV` will be set to `"development"` in development mode.
|
||||
|
||||
You can set environment variables only available to a certain mode by postfixing the `.env` file. For example, if you create a file named `.env.development` in your project root, then the variables declared in that file will only be loaded in development mode.
|
||||
|
||||
You can overwrite the default mode used for a command by passing the `--mode` option flag. For example, if you want to use development variables in the build command, add this to your `package.json` scripts:
|
||||
|
||||
```
|
||||
"dev-build": "vue-cli-service build --mode development",
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
``` js
|
||||
console.log(process.env.VUE_APP_SECRET)
|
||||
```
|
||||
|
||||
During build, `process.env.VUE_APP_SECRET` will be replaced by the corresponding value. In the case of `VUE_APP_SECRET=secret`, it will be replaced by `"secret"`.
|
||||
|
||||
In addition to `VUE_APP_*` variables, there are also two special variables that will always be available in your app code:
|
||||
|
||||
- `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
|
||||
|
||||
All resolved env variables will be available inside `public/index.html` via [lodash template interpolation](https://lodash.com/docs/4.17.5#template):
|
||||
|
||||
- `<%= VAR %>` for unescaped interpolation;
|
||||
- `<%- VAR %>` for HTML-escaped interpolation;
|
||||
- `<% expression %>` for JavaScript control flows.
|
||||
|
||||
For example, to reference static assets copied from the root of `public`, you will need to use the `BASE_URL` variable:
|
||||
|
||||
``` html
|
||||
<link rel="shortcut icon" href="<%= BASE_URL %>favicon.ico">
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
`.local` can also be appended to mode-specific env files, for example `.env.development.local` will be loaded during development, and is ignored by git.
|
||||
@@ -0,0 +1 @@
|
||||
# Plugins and Presets
|
||||
@@ -0,0 +1 @@
|
||||
# Instant Prototyping
|
||||
@@ -0,0 +1 @@
|
||||
# Using the GUI
|
||||
Reference in New Issue
Block a user