diff --git a/docs/config/README.md b/docs/config/README.md index 2c0e342bb..a03185932 100644 --- a/docs/config/README.md +++ b/docs/config/README.md @@ -98,6 +98,10 @@ module.exports = { } ``` + ::: tip + When building in multi-page mode, the webpack config will contain different plugins (there will be multiple instances of `html-webpack-plugin` and `preload-webpack-plugin`). Make sure to run `vue inspect` if you are trying to modify the options for those plugins. + ::: + ### lintOnSave - Type: `boolean` diff --git a/docs/dev-guide/plugin-dev.md b/docs/dev-guide/plugin-dev.md index ed8be6264..fe66ec42a 100644 --- a/docs/dev-guide/plugin-dev.md +++ b/docs/dev-guide/plugin-dev.md @@ -282,6 +282,14 @@ Alternatively, the user can skip the prompts and directly initialize the plugin vue invoke my-plugin --mode awesome ``` +## Distributing the Plugin + +For a CLI plugin to be usable by other developers, it must be published on npm following the name convention `vue-cli-plugin-`. Following the name convention allows your plugin to be: + +- Discoverable by `@vue/cli-service`; +- Discoverable by other developers via searching; +- Installable via `vue add ` or `vue invoke `. + ## Note on Development of Core Plugins ::: tip Note diff --git a/docs/guide/html-and-static-assets.md b/docs/guide/html-and-static-assets.md index d5af6d2a2..38979cb03 100644 --- a/docs/guide/html-and-static-assets.md +++ b/docs/guide/html-and-static-assets.md @@ -8,13 +8,20 @@ The file `public/index.html` is a template that will be processed with [html-web ### Interpolation -Since the index file is used as a template, you can use the [lodash template](https://lodash.com/docs/4.17.10#template) syntax to interpolate values in it. In addition to the [default values exposed by `html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin#writing-your-own-templates), all [client-side env variables](./mode-and-env.md#using-env-variables-in-client-side-code) are also available directly. For example, to use the `BASE_URL` value: +Since the index file is used as a template, you can use the [lodash template](https://lodash.com/docs/4.17.10#template) syntax to interpolate values in it: + +- `<%= VALUE %>` for unescaped interpolation; +- `<%- VALUE %>` for HTML-escaped interpolation; +- `<% expression %>` for JavaScript control flows. + +In addition to the [default values exposed by `html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin#writing-your-own-templates), all [client-side env variables](./mode-and-env.md#using-env-variables-in-client-side-code) are also available directly. For example, to use the `BASE_URL` value: ``` html ``` -See also: [baseUrl](../config/#baseurl) +See also: +- [baseUrl](../config/#baseurl) ### Preload @@ -32,6 +39,25 @@ By default, a Vue CLI app will automatically generate prefetch hints for all Jav The hints are injected using [@vue/preload-webpack-plugin](https://github.com/vuejs/preload-webpack-plugin) and can be modified / deleted via `chainWebpack` as `config.plugin('prefetch')`. +Example: + +``` js +// vue.config.js +module.exports = { + chainWebpack: config => { + // remove the prefetch plugin + config.plugins.delete('prefetch') + + // or: + // modify its options: + config.plugin('prefetch').tap(options => { + options.fileBlackList.push([/myasyncRoute(.)+?\.js$/]) + return options + }) + } +} +``` + ::: tip Prefetch links will consume bandwidth. If you have a large app with many async chunks and your user are primarily mobile and thus bandwidth-aware, you may want to disable prefetch links. ::: diff --git a/docs/guide/mode-and-env.md b/docs/guide/mode-and-env.md index 1c5903b98..cf02c53e7 100644 --- a/docs/guide/mode-and-env.md +++ b/docs/guide/mode-and-env.md @@ -36,6 +36,27 @@ You can overwrite the default mode used for a command by passing the `--mode` op "dev-build": "vue-cli-service build --mode development", ``` +## Example: Staging Mode + +Assuming we have an app with the following `.env` file: + +``` +VUE_APP_TITLE=My App +``` + +And the following `.env.staging` file: + +``` +NODE_ENV=production +VUE_APP_TITLE=My App (staging) +``` + +- `vue-cli-service build` builds a production app, loading `.env`, `.env.production` and `.env.production.local` if they are present; + +- `vue-cli-service build --mode staging` builds a production app in staging mode, using `.env`, `.env.staging` and `.env.staging.local` if they are present. + +In both cases, the app is built as a production app because of the `NODE_ENV`, but in the staging version, `process.env.VUE_APP_TITLE` is overwritten with a different value. + ## 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: @@ -51,19 +72,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 - -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 - -``` +All resolved env variables will be available inside `public/index.html` as discussed in [HTML - Interpolation](./html-and-static-assets.md#interpolation). ## Local Only Variables