docs: clarify modules option in preset-env

docs/options.md

@@ -42,7 +42,15 @@ relative to.
 
 ### `caller`
 
-Type: `Object` with a string-typed `"name"` property.<br />
+Type: An object with the shape of
+```flow
+interface CallerData {
+  name: string;
+  supportsStaticESM?: boolean;
+  supportsDynamicImport?: boolean;
+  supportsTopLevelAwait?: boolean;
+}
+```
 
 Utilities may pass a `caller` object to identify themselves to Babel and pass
 capability-related flags for use by configs, presets and plugins. For example

docs/preset-env.md

@@ -185,11 +185,12 @@ Enable ["loose" transformations](http://2ality.com/2015/12/babel6-loose-mode.htm
 
 `"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false`, defaults to `"auto"`.
 
-Enable transformation of ES6 module syntax to another module type.
+Enable transformation of ES module syntax to another module type. Note that `cjs` is just an alias for `commonjs`.
 
-Setting this to `false` will not transform modules.
+Setting this to `false` will preserve ES modules. Use this only if you intend to ship native ES Modules to browsers. If you are using a bundler with Babel, the default `modules: "auto"` is always preferred.
 
-Also note that `cjs` is just an alias for `commonjs`.
+#### `modules: "auto"`
+By default `@babel/preset-env` uses [`caller`](options.md#caller) data to determine whether ES modules and module features (e.g. `import()`) should be transformed. Generally `caller` data will be specified in the bundler plugins (e.g. `babel-loader`, `@rollup/plugin-babel`) and thus it is not recommended to pass `caller` data yourself -- The passed `caller` may overwrite the one from bundler plugins and in the future you may get suboptimal results if bundlers supports new module features.
 
 ### `debug`
 

website/versioned_docs/version-7.0.0/options.md

@@ -37,7 +37,13 @@ relative to.
 
 ### `caller`
 
-Type: `Object` with a string-typed `"name"` property.<br />
+Type: An object with the shape of
+```flow
+interface CallerData {
+  name: string;
+  supportsStaticESM?: boolean;
+}
+```
 
 Utilities may pass a `caller` object to identify themselves to Babel and pass
 capability-related flags for use by configs, presets and plugins. For example

website/versioned_docs/version-7.0.0/preset-env.md

@@ -176,11 +176,12 @@ Enable ["loose" transformations](http://2ality.com/2015/12/babel6-loose-mode.htm
 
 `"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false`, defaults to `"auto"`.
 
-Enable transformation of ES6 module syntax to another module type.
+Enable transformation of ES module syntax to another module type. Note that `cjs` is just an alias for `commonjs`.
 
-Setting this to `false` will not transform modules.
+Setting this to `false` will preserve ES modules. Use this only if you intend to ship native ES Modules to browsers. If you are using a bundler with Babel, the default `modules: "auto"` is always preferred.
 
-Also note that `cjs` is just an alias for `commonjs`.
+#### `modules: "auto"`
+By default `@babel/preset-env` uses [`caller`](options.md#caller) data to determine whether ES modules and module features (e.g. `import()`) should be transformed. Generally `caller` data will be specified in the bundler plugins (e.g. `babel-loader`, `@rollup/plugin-babel`) and thus it is not recommended to pass `caller` data yourself -- The passed `caller` may overwrite the one from bundler plugins and in the future you may get suboptimal results if bundlers supports new module features.
 
 ### `debug`
 

website/versioned_docs/version-7.1.0/options.md

@@ -43,7 +43,13 @@ relative to.
 
 ### `caller`
 
-Type: `Object` with a string-typed `"name"` property.<br />
+Type: An object with the shape of
+```flow
+interface CallerData {
+  name: string;
+  supportsStaticESM?: boolean;
+}
+```
 
 Utilities may pass a `caller` object to identify themselves to Babel and pass
 capability-related flags for use by configs, presets and plugins. For example

website/versioned_docs/version-7.10.0/preset-env.md

@@ -186,11 +186,12 @@ Enable ["loose" transformations](http://2ality.com/2015/12/babel6-loose-mode.htm
 
 `"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false`, defaults to `"auto"`.
 
-Enable transformation of ES6 module syntax to another module type.
+Enable transformation of ES module syntax to another module type. Note that `cjs` is just an alias for `commonjs`.
 
-Setting this to `false` will not transform modules.
+Setting this to `false` will preserve ES modules. Use this only if you intend to ship native ES Modules to browsers. If you are using a bundler with Babel, the default `modules: "auto"` is always preferred.
 
-Also note that `cjs` is just an alias for `commonjs`.
+#### `modules: "auto"`
+By default `@babel/preset-env` uses [`caller`](options.md#caller) data to determine whether ES modules and module features (e.g. `import()`) should be transformed. Generally `caller` data will be specified in the bundler plugins (e.g. `babel-loader`, `@rollup/plugin-babel`) and thus it is not recommended to pass `caller` data yourself -- The passed `caller` may overwrite the one from bundler plugins and in the future you may get suboptimal results if bundlers supports new module features.
 
 ### `debug`
 

website/versioned_docs/version-7.4.0/preset-env.md

@@ -176,11 +176,12 @@ Enable ["loose" transformations](http://2ality.com/2015/12/babel6-loose-mode.htm
 
 `"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false`, defaults to `"auto"`.
 
-Enable transformation of ES6 module syntax to another module type.
+Enable transformation of ES module syntax to another module type. Note that `cjs` is just an alias for `commonjs`.
 
-Setting this to `false` will not transform modules.
+Setting this to `false` will preserve ES modules. Use this only if you intend to ship native ES Modules to browsers. If you are using a bundler with Babel, the default `modules: "auto"` is always preferred.
 
-Also note that `cjs` is just an alias for `commonjs`.
+#### `modules: "auto"`
+By default `@babel/preset-env` uses [`caller`](options.md#caller) data to determine whether ES modules and module features (e.g. `import()`) should be transformed. Generally `caller` data will be specified in the bundler plugins (e.g. `babel-loader`, `@rollup/plugin-babel`) and thus it is not recommended to pass `caller` data yourself -- The passed `caller` may overwrite the one from bundler plugins and in the future you may get suboptimal results if bundlers supports new module features.
 
 ### `debug`
 

website/versioned_docs/version-7.8.0/options.md

@@ -44,7 +44,15 @@ relative to.
 
 ### `caller`
 
-Type: `Object` with a string-typed `"name"` property.<br />
+Type: An object with the shape of
+```flow
+interface CallerData {
+  name: string;
+  supportsStaticESM?: boolean;
+  supportsDynamicImport?: boolean;
+  supportsTopLevelAwait?: boolean;
+}
+```
 
 Utilities may pass a `caller` object to identify themselves to Babel and pass
 capability-related flags for use by configs, presets and plugins. For example

website/versioned_docs/version-7.8.0/preset-env.md

@@ -176,11 +176,12 @@ Enable ["loose" transformations](http://2ality.com/2015/12/babel6-loose-mode.htm
 
 `"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false`, defaults to `"auto"`.
 
-Enable transformation of ES6 module syntax to another module type.
+Enable transformation of ES module syntax to another module type. Note that `cjs` is just an alias for `commonjs`.
 
-Setting this to `false` will not transform modules.
+Setting this to `false` will preserve ES modules. Use this only if you intend to ship native ES Modules to browsers. If you are using a bundler with Babel, the default `modules: "auto"` is always preferred.
 
-Also note that `cjs` is just an alias for `commonjs`.
+#### `modules: "auto"`
+By default `@babel/preset-env` uses [`caller`](options.md#caller) data to determine whether ES modules and module features (e.g. `import()`) should be transformed. Generally `caller` data will be specified in the bundler plugins (e.g. `babel-loader`, `@rollup/plugin-babel`) and thus it is not recommended to pass `caller` data yourself -- The passed `caller` may overwrite the one from bundler plugins and in the future you may get suboptimal results if bundlers supports new module features.
 
 ### `debug`
 

website/versioned_docs/version-7.8.4/options.md

@@ -44,7 +44,15 @@ relative to.
 
 ### `caller`
 
-Type: `Object` with a string-typed `"name"` property.<br />
+Type: An object with the shape of
+```flow
+interface CallerData {
+  name: string;
+  supportsStaticESM?: boolean;
+  supportsDynamicImport?: boolean;
+  supportsTopLevelAwait?: boolean;
+}
+```
 
 Utilities may pass a `caller` object to identify themselves to Babel and pass
 capability-related flags for use by configs, presets and plugins. For example

website/versioned_docs/version-7.9.0/options.md

@@ -43,7 +43,15 @@ relative to.
 
 ### `caller`
 
-Type: `Object` with a string-typed `"name"` property.<br />
+Type: An object with the shape of
+```flow
+interface CallerData {
+  name: string;
+  supportsStaticESM?: boolean;
+  supportsDynamicImport?: boolean;
+  supportsTopLevelAwait?: boolean;
+}
+```
 
 Utilities may pass a `caller` object to identify themselves to Babel and pass
 capability-related flags for use by configs, presets and plugins. For example

website/versioned_docs/version-7.9.0/preset-env.md

@@ -186,11 +186,12 @@ Enable ["loose" transformations](http://2ality.com/2015/12/babel6-loose-mode.htm
 
 `"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false`, defaults to `"auto"`.
 
-Enable transformation of ES6 module syntax to another module type.
+Enable transformation of ES module syntax to another module type. Note that `cjs` is just an alias for `commonjs`.
 
-Setting this to `false` will not transform modules.
+Setting this to `false` will preserve ES modules. Use this only if you intend to ship native ES Modules to browsers. If you are using a bundler with Babel, the default `modules: "auto"` is always preferred.
 
-Also note that `cjs` is just an alias for `commonjs`.
+#### `modules: "auto"`
+By default `@babel/preset-env` uses [`caller`](options.md#caller) data to determine whether ES modules and module features (e.g. `import()`) should be transformed. Generally `caller` data will be specified in the bundler plugins (e.g. `babel-loader`, `@rollup/plugin-babel`) and thus it is not recommended to pass `caller` data yourself -- The passed `caller` may overwrite the one from bundler plugins and in the future you may get suboptimal results if bundlers supports new module features.
 
 ### `debug`