feat: deprecate confusing baseUrl option, use publicPath instead. (#3143)

* feat: deprecate confusing `baseUrl` option, use `publicPath` instead.

* fix: do not touch CHANGELOG.md

* docs: links referring baseUrl now changed to publicPath

Author: haoqunjiang

docs/config/README.md

@@ -31,17 +31,21 @@ module.exports = {
 
 ### baseUrl
 
+Deprecated since Vue CLI 3.3, please use [`publicPath`](#publicPath) instead.
+
+### publicPath
+
 - Type: `string`
 - Default: `'/'`
 
-  The base URL your application bundle will be deployed at. This is the equivalent of webpack's `output.publicPath`, but Vue CLI also needs this value for other purposes, so you should **always use `baseUrl` instead of modifying webpack `output.publicPath`**.
+  The base URL your application bundle will be deployed at (known as `baseUrl` before Vue CLI 3.3). This is the equivalent of webpack's `output.publicPath`, but Vue CLI also needs this value for other purposes, so you should **always use `publicPath` instead of modifying webpack `output.publicPath`**.
 
-  By default, Vue CLI assumes 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 using this option. For example, if your app is deployed at `https://www.foobar.com/my-app/`, set `baseUrl` to `'/my-app/'`.
+  By default, Vue CLI assumes 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 using this option. For example, if your app is deployed at `https://www.foobar.com/my-app/`, set `publicPath` to `'/my-app/'`.
 
   The value can also be set to an empty string (`''`) or a relative path (`./`) so that all assets are linked using relative paths. This allows the built bundle to be deployed under any public path, or used in a file system based environment like a Cordova hybrid app.
 
-  ::: warning Limitations of relative baseUrl
-  Relative `baseUrl` has some limitations and should be avoided when:
+  ::: warning Limitations of relative publicPath
+  Relative `publicPath` has some limitations and should be avoided when:
 
   - You are using HTML5 `history.pushState` routing;
 
@@ -52,7 +56,7 @@ module.exports = {
 
   ``` js
   module.exports = {
-    baseUrl: process.env.NODE_ENV === 'production'
+    publicPath: process.env.NODE_ENV === 'production'
       ? '/production-sub-path/'
       : '/'
   }
@@ -304,7 +308,7 @@ module.exports = {
 
   - Some values like `host`, `port` and `https` may be overwritten by command line flags.
 
-  - Some values like `publicPath` and `historyApiFallback` should not be modified as they need to be synchronized with [baseUrl](#baseurl) for the dev server to function properly.
+  - Some values like `publicPath` and `historyApiFallback` should not be modified as they need to be synchronized with [publicPath](#baseurl) for the dev server to function properly.
 
 ### devServer.proxy
 

docs/guide/deployment.md

@@ -4,11 +4,11 @@
 
 If you are using Vue CLI along with a backend framework that handles static assets as part of its deployment, all you need to do is make sure Vue CLI generates the built files in the correct location, and then follow the deployment instruction of your backend framework.
 
-If you are developing your frontend app separately from your backend - i.e. your backend exposes an API for your frontend to talk to, then your frontend is essentially a purely static app. You can deploy the built content in the `dist` directory to any static file server, but make sure to set the correct [baseUrl](../config/#baseurl).
+If you are developing your frontend app separately from your backend - i.e. your backend exposes an API for your frontend to talk to, then your frontend is essentially a purely static app. You can deploy the built content in the `dist` directory to any static file server, but make sure to set the correct [publicPath](../config/#publicpath).
 
 ### Previewing Locally
 
-The `dist` directory is meant to be served by an HTTP server (unless you've configured `baseUrl` to be a relative value), so it will not work if you open `dist/index.html` directly over `file://` protocol. The easiest way to preview your production build locally is using a Node.js static file server, for example [serve](https://github.com/zeit/serve):
+The `dist` directory is meant to be served by an HTTP server (unless you've configured `publicPath` to be a relative value), so it will not work if you open `dist/index.html` directly over `file://` protocol. The easiest way to preview your production build locally is using a Node.js static file server, for example [serve](https://github.com/zeit/serve):
 
 ``` bash
 npm install -g serve
@@ -35,15 +35,15 @@ If you are using the PWA plugin, your app must be served over HTTPS so that [Ser
 
 ### GitHub Pages
 
-1. Set correct `baseUrl` in `vue.config.js`.
+1. Set correct `publicPath` in `vue.config.js`.
 
-    If you are deploying to `https://<USERNAME>.github.io/`, you can omit `baseUrl` as it defaults to `"/"`.
+    If you are deploying to `https://<USERNAME>.github.io/`, you can omit `publicPath` as it defaults to `"/"`.
 
-    If you are deploying to `https://<USERNAME>.github.io/<REPO>/`, (i.e. your repository is at `https://github.com/<USERNAME>/<REPO>`), set `baseUrl` to `"/<REPO>/"`. For example, if your repo name is "my-project", your `vue.config.js` should look like this:
+    If you are deploying to `https://<USERNAME>.github.io/<REPO>/`, (i.e. your repository is at `https://github.com/<USERNAME>/<REPO>`), set `publicPath` to `"/<REPO>/"`. For example, if your repo name is "my-project", your `vue.config.js` should look like this:
 
     ``` js
     module.exports = {
-      baseUrl: process.env.NODE_ENV === 'production'
+      publicPath: process.env.NODE_ENV === 'production'
         ? '/my-project/'
         : '/'
     }
@@ -112,7 +112,7 @@ Typically, your static website will be hosted on https://yourUserName.gitlab.io/
 // make sure you update `yourProjectName` with the name of your GitLab project
 
 module.exports = {
-  baseUrl: process.env.NODE_ENV === 'production'
+  publicPath: process.env.NODE_ENV === 'production'
     ? '/yourProjectName/'
     : '/'
 }
@@ -291,11 +291,11 @@ Verify your project is successfully published by Surge by visiting `myawesomepro
 
 1. As described in the [Bitbucket documentation](https://confluence.atlassian.com/bitbucket/publishing-a-website-on-bitbucket-cloud-221449776.html) you need to create a repository named exactly `<USERNAME>.bitbucket.io`.
 
-2. It is possible to publish to a subfolder of the main repository, for instance if you want to have multiple websites. In that case set correct `baseUrl` in `vue.config.js`.
+2. It is possible to publish to a subfolder of the main repository, for instance if you want to have multiple websites. In that case set correct `publicPath` in `vue.config.js`.
 
-    If you are deploying to `https://<USERNAME>.bitbucket.io/`, you can omit `baseUrl` as it defaults to `"/"`.
+    If you are deploying to `https://<USERNAME>.bitbucket.io/`, you can omit `publicPath` as it defaults to `"/"`.
 
-    If you are deploying to `https://<USERNAME>.bitbucket.io/<SUBFOLDER>/`, set `baseUrl` to `"/<SUBFOLDER>/"`. In this case the directory structure of the repository should reflect the url structure, for instance the repository should have a `/<SUBFOLDER>` directory.
+    If you are deploying to `https://<USERNAME>.bitbucket.io/<SUBFOLDER>/`, set `publicPath` to `"/<SUBFOLDER>/"`. In this case the directory structure of the repository should reflect the url structure, for instance the repository should have a `/<SUBFOLDER>` directory.
 
 3. Inside your project, create `deploy.sh` with the following content and run it to deploy:
 

docs/guide/html-and-static-assets.md

@@ -21,7 +21,7 @@ In addition to the [default values exposed by `html-webpack-plugin`](https://git
 ```
 
 See also:
-- [baseUrl](../config/#baseurl)
+- [publicPath](../config/#publicpath)
 
 ### Preload
 
@@ -166,7 +166,7 @@ Note we recommend importing assets as part of your module dependency graph so th
 - 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 [baseUrl](../config/#baseurl):
+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 [publicPath](../config/#publicpath):
 
 - In `public/index.html` or other HTML files used as templates by `html-webpack-plugin`, you need to prefix the link with `<%= BASE_URL %>`:
 
@@ -179,15 +179,15 @@ The `public` directory is provided as an **escape hatch**, and when you referenc
   ``` js
   data () {
     return {
-      baseUrl: process.env.BASE_URL
+      publicPath: process.env.BASE_URL
     }
   }
   ```
 
   Then:
 
   ``` html
-  <img :src="`${baseUrl}my-image.png`">
+  <img :src="`${publicPath}my-image.png`">
   ```
 
 ### When to use the `public` folder

docs/guide/mode-and-env.md

@@ -81,7 +81,7 @@ During build, `process.env.VUE_APP_SECRET` will be replaced by the corresponding
 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.
+- `BASE_URL` - this corresponds to the `publicPath` option in `vue.config.js` and is the base path your app is deployed at.
 
 All resolved env variables will be available inside `public/index.html` as discussed in [HTML - Interpolation](./html-and-static-assets.md#interpolation).
 

docs/guide/webpack.md

@@ -18,7 +18,7 @@ module.exports = {
 The object will be merged into the final webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
 
 ::: warning
-Some webpack options are set based on values in `vue.config.js` and should not be mutated directly. For example, instead of modifying `output.path`, you should use the `outputDir` option in `vue.config.js`; instead of modifying `output.publicPath`, you should use the `baseUrl` option in `vue.config.js`. This is because the values in `vue.config.js` will be used in multiple places inside the config to ensure everything works properly together.
+Some webpack options are set based on values in `vue.config.js` and should not be mutated directly. For example, instead of modifying `output.path`, you should use the `outputDir` option in `vue.config.js`; instead of modifying `output.publicPath`, you should use the `publicPath` option in `vue.config.js`. This is because the values in `vue.config.js` will be used in multiple places inside the config to ensure everything works properly together.
 :::
 
 If you need conditional behavior based on the environment, or want to directly mutate the config, use a function (which will be lazy evaluated after the env variables are set). The function receives the resolved config as the argument. Inside the function, you can either mutate the config directly, OR return an object which will be merged:

docs/ru/config/README.md

@@ -29,19 +29,19 @@ module.exports = {
 }
 ```
 
-### baseUrl
+### publicPath
 
 - Тип: `string`
 - По умолчанию: `'/'`
 
-  Базовый URL-адрес сборки вашего приложения, по которому оно будет опубликовано. Это аналог опции webpack `output.publicPath`, но Vue CLI также использует это значение в других целях, поэтому вы должны **всегда использовать `baseUrl` вместо изменения опции `output.publicPath`**.
+  Базовый URL-адрес сборки вашего приложения, по которому оно будет опубликовано. Это аналог опции webpack `output.publicPath`, но Vue CLI также использует это значение в других целях, поэтому вы должны **всегда использовать `publicPath` вместо изменения опции `output.publicPath`**.
 
-  По умолчанию Vue CLI считает, что публикация будет выполнена в корень домена, например `https://www.my-app.com/`. Если приложение публикуется в подкаталог, то необходимо указать этот путь с помощью этой опции. Например, если приложение будет публиковаться по адресу `https://www.foobar.com/my-app/`, установите `baseUrl` в значение `'/my-app/'`.
+  По умолчанию Vue CLI считает, что публикация будет выполнена в корень домена, например `https://www.my-app.com/`. Если приложение публикуется в подкаталог, то необходимо указать этот путь с помощью этой опции. Например, если приложение будет публиковаться по адресу `https://www.foobar.com/my-app/`, установите `publicPath` в значение `'/my-app/'`.
 
   Значение также может быть пустой строкой (`''`) или относительным путём (`./`), чтобы все ресурсы подключались через относительные пути. Это позволит публиковать сборку в любой публичный каталог, или использовать в окружении файловой системы, например в гибридном приложении Cordova.
 
-  ::: warning Ограничения относительного baseUrl
-  Относительный `baseUrl` имеет некоторые ограничения и его следует избегать если:
+  ::: warning Ограничения относительного publicPath
+  Относительный `publicPath` имеет некоторые ограничения и его следует избегать если:
 
   - Вы используете маршрутизацию HTML5 `history.pushState`;
 
@@ -52,7 +52,7 @@ module.exports = {
 
   ``` js
   module.exports = {
-    baseUrl: process.env.NODE_ENV === 'production'
+    publicPath: process.env.NODE_ENV === 'production'
       ? '/production-sub-path/'
       : '/'
   }
@@ -304,7 +304,7 @@ module.exports = {
 
   - Некоторые значения, такие как `host`, `port` и `https`, могут перезаписываться флагами командной строки.
 
-  - Некоторые значения, такие как `publicPath` и `historyApiFallback`, нельзя изменять, поскольку они должны быть синхронизированы с [baseUrl](#baseurl) для правильной работы сервера разработки.
+  - Некоторые значения, такие как `publicPath` и `historyApiFallback`, нельзя изменять, поскольку они должны быть синхронизированы с [publicPath](#baseurl) для правильной работы сервера разработки.
 
 ### devServer.proxy