docs: more details for Babel preset and polyfill handling

Author: yyx990803

packages/@vue/babel-preset-app/README.md

@@ -7,12 +7,11 @@ This is the default Babel preset used in all Vue CLI projects.
 - [babel-preset-env](https://github.com/babel/babel/tree/master/packages/babel-preset-env)
   - `modules: false`
     - auto set to `'commonjs'` in Jest tests
-  - [`useBuiltIns: 'usage'`](https://github.com/babel/babel/tree/master/packages/babel-preset-env#usebuiltins-usage)
-    - ensures polyfills are imported on-demand
+  - [`useBuiltIns: 'usage'`](#usebuiltins)
   - `targets` is determined:
     - using `browserslist` field in `package.json` when building for browsers
     - set to `{ node: 'current' }` when running unit tests in Node.js
-- Includes `Promise` and `Object.assign` polyfills by default so that they are usable even in non-transpiled dependencies (only for environments that need them)
+- Includes `Promise` polyfill by default so that they are usable even in non-transpiled dependencies (only for environments that need it)
 - [@babel/plugin-transform-runtime](https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-runtime)
   - Only enabled for helpers since polyfills are handled by `babel-preset-env`
 - [dynamic import syntax](https://github.com/tc39/proposal-dynamic-import)
@@ -26,50 +25,57 @@ This is the default Babel preset used in all Vue CLI projects.
 
 ## Options
 
-- **modules**
+### modules
 
-  Default:
+- Default:
   - `false` when building with webpack
   - `'commonjs'` when running tests in Jest.
 
-  Explicitly set `modules` option for `babel-preset-env`. See [babel-preset-env docs](https://github.com/babel/babel/tree/master/packages/babel-preset-env#modules) for more details.
+Explicitly set `modules` option for `babel-preset-env`. See [babel-preset-env docs](https://github.com/babel/babel/tree/master/packages/babel-preset-env#modules) for more details.
 
-- **targets**
+### targets
 
-  Default:
+- Default:
   - determined from `browserslist` field in `package.json` when building for browsers
   - set to `{ node: 'current' }` when running unit tests in Node.js
 
-  Explicitly set `targets` option for `babel-preset-env`. See [babel-preset-env docs](https://github.com/babel/babel/tree/master/packages/babel-preset-env#targets) for more details.
+Explicitly set `targets` option for `babel-preset-env`. See [babel-preset-env docs](https://github.com/babel/babel/tree/master/packages/babel-preset-env#targets) for more details.
 
-- **useBuiltIns**
+### useBuiltIns
 
-  Default: `'usage'`
+- Default: `'usage'`
+- Allowed values: `'usage' | 'entry' | false`
 
-  Explicitly set `useBuiltIns` option for `babel-preset-env`.
+Explicitly set `useBuiltIns` option for `babel-preset-env`.
 
-  The default value is `'usage'`, which adds imports to polyfills based on the usage in transpiled code. Note that the usage detection does not apply to your dependencies (which are excluded by `cli-plugin-babel` by default). If one of your dependencies need polyfills, you have three options:
+The default value is `'usage'`, which adds imports to polyfills based on the usage in transpiled code. For example, if you use `Object.assign` in your code, the corresponding polyfill will be auto-imported if your target environment does not supports it.
 
-  1. Add that dependency to the `transpileDependencies` option in `vue.config.js`. This would enable the same usage-based polyfill detection for that dependency as well;
+Note that the usage detection does not apply to your dependencies (which are excluded by `cli-plugin-babel` by default). If one of your dependencies need polyfills, you have a few options:
 
-  2. OR, you can explicitly include the needed polyfills using the [polyfills](#polyfills) option for this preset.
+1. **If the dependency is written in an ES version that your target environments do not support:** Add that dependency to the `transpileDependencies` option in `vue.config.js`. This would enable both syntax transforms and usage-based polyfill detection for that dependency.
 
-  3. Use `useBuiltIns: 'entry'` and then add `import '@babel/polyfill'` to your entry file. This will import **ALL** polyfills based on your `browserslist` targets so that you don't need to worry about dependency polyfills anymore, but will likely bloat your final bundle with some unused polyfills.
+2. **If the dependency ships ES5 code and explicitly lists the polyfills needed:** you can pre-include the needed polyfills using the [polyfills](#polyfills) option for this preset.
 
-  See [babel-preset-env docs](https://github.com/babel/babel/tree/master/packages/babel-preset-env#usebuiltins) for more details.
+3. **If the dependency ships ES5 code, but uses ES6+ features without explicitly listing polyfill requirements (e.g. Vuetify):** Use `useBuiltIns: 'entry'` and then add `import '@babel/polyfill'` to your entry file. This will import **ALL** polyfills based on your `browserslist` targets so that you don't need to worry about dependency polyfills anymore, but will likely increase your final bundle size with some unused polyfills.
 
-- **polyfills**
+See [babel-preset-env docs](https://github.com/babel/babel/tree/master/packages/babel-preset-env#usebuiltins) for more details.
 
-  Default: `['es6.promise', 'es6.object.assign']`
+### polyfills
 
-  A list of [core-js](https://github.com/zloirock/core-js) polyfills to force-include when using `useBuiltIns: 'usage'`.
+- Default: `['es6.promise']`
 
-  Use this option when you have 3rd party dependencies that are not processed by Babel but have specific polyfill requirements. **These polyfills are automatically excluded if they are not needed for your target environments specified via `browserslist`**.
+A list of [core-js](https://github.com/zloirock/core-js) polyfills to pre-include when using `useBuiltIns: 'usage'`. **These polyfills are automatically excluded if they are not needed for your target environments**.
 
-- **jsx**
+Use this option when you have 3rd party dependencies that are not processed by Babel but have specific polyfill requirements (e.g. Axios and Vuex require Promise support).
 
-  Default: `true`. Set to `false` to disable JSX support.
+### jsx
 
-- **loose**
+- Default: `true`.
 
-  Default: `false`. Setting this to `true` will generate code that is more performant but less spec-compliant.
+Set to `false` to disable JSX support.
+
+### loose
+
+- Default: `false`.
+
+Setting this to `true` will generate code that is more performant but less spec-compliant.

packages/@vue/babel-preset-app/index.js

@@ -1,8 +1,7 @@
 const path = require('path')
 
 const defaultPolyfills = [
-  'es6.promise',
-  'es6.object.assign'
+  'es6.promise'
 ]
 
 function getPolyfills (targets, includes, { ignoreBrowserslistConfig, configPath }) {