docs: add targets option to @babel/plugin-transform-runtime

docs/plugin-transform-runtime.md

@@ -36,6 +36,44 @@ The transformer will alias these built-ins to `core-js` so you can use them seam
 
 See the [technical details](#technical-details) section for more information on how this works and the types of transformations that occur.
 
+## Browserslist Integration
+
+For browser- or Electron-based projects, we recommend using a [`.browserslistrc`](https://github.com/browserslist/browserslist) file to specify targets. You may already have this configuration file as it is used by many tools in the ecosystem, like [autoprefixer](https://github.com/postcss/autoprefixer), [stylelint](https://stylelint.io/), [eslint-plugin-compat](https://github.com/amilajack/eslint-plugin-compat) and many others.
+
+Assuming the `corejs` option is not set to `false`, by default `@babel/plugin-transform-runtime` will use [browserslist config sources](https://github.com/ai/browserslist#queries) _unless_ either the [targets](#targets) or [ignoreBrowserslistConfig](#ignorebrowserslistconfig) options are set.
+
+For example, to only include polyfills and code transforms needed for users whose browsers have >0.25% market share (ignoring browsers without security updates like IE 10 and BlackBerry):
+
+[Options](options.md#presets)
+
+```json
+{
+  "plugins": [
+    [
+      "@babel/plugin-transform-runtime",
+      {
+        "corejs": 3
+      }
+    ]
+  ]
+}
+```
+
+**browserslist**
+
+```
+> 0.25%
+not dead
+```
+
+or
+
+**package.json**
+
+```
+"browserslist": "> 0.25%, not dead"
+```
+
 ## Usage
 
 ### With a configuration file (Recommended)
@@ -48,7 +86,7 @@ Without options:
 }
 ```
 
-With options (and their defaults):
+With options (and their defaults, excluding `configPath`):
 
 ```json
 {
@@ -59,7 +97,9 @@ With options (and their defaults):
         "absoluteRuntime": false,
         "corejs": false,
         "helpers": true,
+        "ignoreBrowserslistConfig": false,
         "regenerator": true,
+        "targets": {},
         "useESModules": false,
         "version": "7.0.0-beta.0"
       }
@@ -123,8 +163,105 @@ For more information, see [Helper aliasing](#helper-aliasing).
 
 Toggles whether or not generator functions are transformed to use a regenerator runtime that does not pollute the global scope.
 
+When generator functions are supported by your `targets`, generator functions are not transformed to use regenerator runtime even if this option is set to `true`.
+
 For more information, see [Regenerator aliasing](#regenerator-aliasing).
 
+### `targets`
+
+`string | Array<string> | { [string]: string }`, defaults to `{}`.
+
+Describes the environments you support/target for your project.
+
+This can either be a [browserslist-compatible](https://github.com/ai/browserslist) query (with [caveats](#ineffective-browserslist-queries)):
+
+```json
+{
+  "targets": "> 0.25%, not dead"
+}
+```
+
+Or an object of minimum environment versions to support:
+
+```json
+{
+  "targets": {
+    "chrome": "58",
+    "ie": "11"
+  }
+}
+```
+
+Example environments: `chrome`, `opera`, `edge`, `firefox`, `safari`, `ie`, `ios`, `android`, `node`, `electron`.
+
+Sidenote, if no targets are specified and `corejs` is not set to `false`, then `@babel/plugin-transform-runtime` will transform all ECMAScript 2015+ code by default.
+
+> We don't recommend using `plugin-transfrom-runtime` this way because it doesn't take advantage of its ability to target specific browsers.
+
+```json
+{
+  "presets": ["@babel/plugin-transform-runtime"]
+}
+```
+
+#### `targets.esmodules`
+
+`boolean`.
+
+You may also target browsers supporting ES Modules (https://www.ecma-international.org/ecma-262/6.0/#sec-modules). When specifying this option, the browsers field will be ignored. You can use this approach in combination with `<script type="module"></script>` to conditionally serve smaller scripts to users (https://jakearchibald.com/2017/es-modules-in-browsers/#nomodule-for-backwards-compatibility).
+
+> _Please note_: when specifying the esmodules target, browsers targets will be ignored.
+
+```json
+{
+  "plugins": [
+    [
+      "@babel/plugin-transform-runtime",
+      {
+        "corejs": 3,
+        "targets": {
+          "esmodules": true
+        }
+      }
+    ]
+  ]
+}
+```
+
+#### `targets.node`
+
+`string | "current" | true`.
+
+If you want to compile against the current node version, you can specify `"node": true` or `"node": "current"`, which would be the same as `"node": process.versions.node`.
+
+#### `targets.safari`
+
+`string | "tp"`.
+
+If you want to compile against the [technology preview](https://developer.apple.com/safari/technology-preview/) version of Safari, you can specify `"safari": "tp"`.
+
+#### `targets.browsers`
+
+`string | Array<string>`.
+
+A query to select browsers (ex: last 2 versions, > 5%, safari tp) using [browserslist](https://github.com/ai/browserslist).
+
+Note, browsers' results are overridden by explicit items from `targets`.
+
+> Note: this will be removed in later version in favor of just setting "targets" to a query directly.
+
+### `configPath`
+
+`string`, defaults to `process.cwd()`
+
+The starting point where the config search for browserslist will start, and ascend to the system root until found.
+
+### `ignoreBrowserslistConfig`
+
+`boolean`, defaults to `false`
+
+Toggles whether or not [browserslist config sources](https://github.com/ai/browserslist#queries) are used, which includes searching for any browserslist files or referencing the browserslist key inside package.json. This is useful for projects that use a browserslist config for files that won't be compiled with Babel.
+
 ### `useBuiltIns`
 
 > This option was removed in v7 by just making it the default.
@@ -359,3 +496,9 @@ var Person = function Person() {
   (0, _classCallCheck3.default)(this, Person);
 };
 ```
+
+## Caveats
+
+### Ineffective browserslist queries
+
+While `op_mini all` is a valid browserslist query, `plugin-transform-runtime` currently ignores it due to [lack of support data](https://github.com/kangax/compat-table/issues/1057) for Opera Mini.