Add targets option to @babel/plugin-transform-runtime

docs/plugin-transform-runtime.md

@@ -60,6 +60,7 @@ With options (and their defaults):
         "corejs": false,
         "helpers": true,
         "regenerator": true,
+        "targets": {},
         "useESModules": false,
         "version": "7.0.0-beta.0"
       }
@@ -123,8 +124,93 @@ 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 the `targets` option is not set and `corejs` is not set to `false`, then `@babel/plugin-transform-runtime` will transform all ECMAScript 2015+ code.
+
+> 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.
+
 ### `useBuiltIns`
 
 > This option was removed in v7 by just making it the default.
@@ -359,3 +445,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.