From 684c11b5b4760e9146fb86a9bfedd6388ca74cb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hu=C3=A1ng=20J=C3=B9nli=C3=A0ng?= Date: Mon, 27 Jul 2020 17:26:14 -0400 Subject: [PATCH 1/4] docs: clarify modules option in preset-env --- docs/options.md | 10 +++++++++- docs/preset-env.md | 7 ++++--- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/options.md b/docs/options.md index c731d0e419..3963fe2f86 100644 --- a/docs/options.md +++ b/docs/options.md @@ -42,7 +42,15 @@ relative to. ### `caller` -Type: `Object` with a string-typed `"name"` property.
+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 diff --git a/docs/preset-env.md b/docs/preset-env.md index f0cee0c3ed..107965bc83 100644 --- a/docs/preset-env.md +++ b/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 module. This is only favored if you intend to ship native ES Module 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 module 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 suboptimized results if bundlers supports new module features. ### `debug` From f95c4faea0786fd02fefe9a4c77bd803f605a8b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hu=C3=A1ng=20J=C3=B9nli=C3=A0ng?= Date: Tue, 28 Jul 2020 09:53:50 -0400 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Brian Ng --- docs/preset-env.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/preset-env.md b/docs/preset-env.md index 107965bc83..74cc18a176 100644 --- a/docs/preset-env.md +++ b/docs/preset-env.md @@ -187,10 +187,10 @@ Enable ["loose" transformations](http://2ality.com/2015/12/babel6-loose-mode.htm Enable transformation of ES module syntax to another module type. Note that `cjs` is just an alias for `commonjs`. -Setting this to `false` will preserve ES module. This is only favored if you intend to ship native ES Module to browsers. If you are using a bundler with Babel, the default `modules: "auto"` is always preferred. +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. #### `modules: "auto"` -By default `@babel/preset-env` uses [`caller`](options.md#caller) data to determine whether ES module 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 suboptimized results if bundlers supports new module features. +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` From 637e40e83fe21c9ddcd7ebf262bfec0843d9f5d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hu=C3=A1ng=20J=C3=B9nli=C3=A0ng?= Date: Tue, 28 Jul 2020 10:18:51 -0400 Subject: [PATCH 3/4] backport changes --- website/versioned_docs/version-7.0.0/preset-env.md | 7 ++++--- website/versioned_docs/version-7.1.0/options.md | 8 +++++++- website/versioned_docs/version-7.10.0/preset-env.md | 7 ++++--- website/versioned_docs/version-7.4.0/preset-env.md | 7 ++++--- website/versioned_docs/version-7.8.0/options.md | 10 +++++++++- website/versioned_docs/version-7.8.0/preset-env.md | 7 ++++--- website/versioned_docs/version-7.8.4/options.md | 10 +++++++++- website/versioned_docs/version-7.9.0/options.md | 10 +++++++++- website/versioned_docs/version-7.9.0/preset-env.md | 7 ++++--- 9 files changed, 54 insertions(+), 19 deletions(-) diff --git a/website/versioned_docs/version-7.0.0/preset-env.md b/website/versioned_docs/version-7.0.0/preset-env.md index 426489419d..c7030fb242 100644 --- a/website/versioned_docs/version-7.0.0/preset-env.md +++ b/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` diff --git a/website/versioned_docs/version-7.1.0/options.md b/website/versioned_docs/version-7.1.0/options.md index d22bc45277..8e0fbb9d1c 100644 --- a/website/versioned_docs/version-7.1.0/options.md +++ b/website/versioned_docs/version-7.1.0/options.md @@ -43,7 +43,13 @@ relative to. ### `caller` -Type: `Object` with a string-typed `"name"` property.
+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 diff --git a/website/versioned_docs/version-7.10.0/preset-env.md b/website/versioned_docs/version-7.10.0/preset-env.md index a1f0390a89..2e48cf34f0 100644 --- a/website/versioned_docs/version-7.10.0/preset-env.md +++ b/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` diff --git a/website/versioned_docs/version-7.4.0/preset-env.md b/website/versioned_docs/version-7.4.0/preset-env.md index ecf998a495..04553d6c35 100644 --- a/website/versioned_docs/version-7.4.0/preset-env.md +++ b/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` diff --git a/website/versioned_docs/version-7.8.0/options.md b/website/versioned_docs/version-7.8.0/options.md index 952df0b9db..2a76f7f656 100644 --- a/website/versioned_docs/version-7.8.0/options.md +++ b/website/versioned_docs/version-7.8.0/options.md @@ -44,7 +44,15 @@ relative to. ### `caller` -Type: `Object` with a string-typed `"name"` property.
+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 diff --git a/website/versioned_docs/version-7.8.0/preset-env.md b/website/versioned_docs/version-7.8.0/preset-env.md index 937db1fad9..4d7b177063 100644 --- a/website/versioned_docs/version-7.8.0/preset-env.md +++ b/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` diff --git a/website/versioned_docs/version-7.8.4/options.md b/website/versioned_docs/version-7.8.4/options.md index 1c60258d20..adeab1212d 100644 --- a/website/versioned_docs/version-7.8.4/options.md +++ b/website/versioned_docs/version-7.8.4/options.md @@ -44,7 +44,15 @@ relative to. ### `caller` -Type: `Object` with a string-typed `"name"` property.
+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 diff --git a/website/versioned_docs/version-7.9.0/options.md b/website/versioned_docs/version-7.9.0/options.md index 145a1a1eb6..09f5e013d6 100644 --- a/website/versioned_docs/version-7.9.0/options.md +++ b/website/versioned_docs/version-7.9.0/options.md @@ -43,7 +43,15 @@ relative to. ### `caller` -Type: `Object` with a string-typed `"name"` property.
+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 diff --git a/website/versioned_docs/version-7.9.0/preset-env.md b/website/versioned_docs/version-7.9.0/preset-env.md index 76e27700d5..39409ac9bf 100644 --- a/website/versioned_docs/version-7.9.0/preset-env.md +++ b/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` From 17d14a5e8faeae9016cbd0b5e3d3999ee49c3a71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hu=C3=A1ng=20J=C3=B9nli=C3=A0ng?= Date: Tue, 28 Jul 2020 16:10:29 -0400 Subject: [PATCH 4/4] address review comments --- docs/options.md | 6 +++--- website/versioned_docs/version-7.0.0/options.md | 8 +++++++- website/versioned_docs/version-7.1.0/options.md | 2 +- website/versioned_docs/version-7.8.0/options.md | 6 +++--- website/versioned_docs/version-7.8.4/options.md | 6 +++--- website/versioned_docs/version-7.9.0/options.md | 6 +++--- 6 files changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/options.md b/docs/options.md index 3963fe2f86..c495c3ea24 100644 --- a/docs/options.md +++ b/docs/options.md @@ -46,9 +46,9 @@ Type: An object with the shape of ```flow interface CallerData { name: string; - supportsStaticESM: boolean; - supportsDynamicImport: boolean; - supportsTopLevelAwait: boolean; + supportsStaticESM?: boolean; + supportsDynamicImport?: boolean; + supportsTopLevelAwait?: boolean; } ``` diff --git a/website/versioned_docs/version-7.0.0/options.md b/website/versioned_docs/version-7.0.0/options.md index 97e0908484..ad0cc2cd9e 100644 --- a/website/versioned_docs/version-7.0.0/options.md +++ b/website/versioned_docs/version-7.0.0/options.md @@ -37,7 +37,13 @@ relative to. ### `caller` -Type: `Object` with a string-typed `"name"` property.
+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 diff --git a/website/versioned_docs/version-7.1.0/options.md b/website/versioned_docs/version-7.1.0/options.md index 8e0fbb9d1c..92e0eac4f6 100644 --- a/website/versioned_docs/version-7.1.0/options.md +++ b/website/versioned_docs/version-7.1.0/options.md @@ -47,7 +47,7 @@ Type: An object with the shape of ```flow interface CallerData { name: string; - supportsStaticESM: boolean; + supportsStaticESM?: boolean; } ``` diff --git a/website/versioned_docs/version-7.8.0/options.md b/website/versioned_docs/version-7.8.0/options.md index 2a76f7f656..1eeda3fe92 100644 --- a/website/versioned_docs/version-7.8.0/options.md +++ b/website/versioned_docs/version-7.8.0/options.md @@ -48,9 +48,9 @@ Type: An object with the shape of ```flow interface CallerData { name: string; - supportsStaticESM: boolean; - supportsDynamicImport: boolean; - supportsTopLevelAwait: boolean; + supportsStaticESM?: boolean; + supportsDynamicImport?: boolean; + supportsTopLevelAwait?: boolean; } ``` diff --git a/website/versioned_docs/version-7.8.4/options.md b/website/versioned_docs/version-7.8.4/options.md index adeab1212d..56375f4da4 100644 --- a/website/versioned_docs/version-7.8.4/options.md +++ b/website/versioned_docs/version-7.8.4/options.md @@ -48,9 +48,9 @@ Type: An object with the shape of ```flow interface CallerData { name: string; - supportsStaticESM: boolean; - supportsDynamicImport: boolean; - supportsTopLevelAwait: boolean; + supportsStaticESM?: boolean; + supportsDynamicImport?: boolean; + supportsTopLevelAwait?: boolean; } ``` diff --git a/website/versioned_docs/version-7.9.0/options.md b/website/versioned_docs/version-7.9.0/options.md index 09f5e013d6..abe0bd23c6 100644 --- a/website/versioned_docs/version-7.9.0/options.md +++ b/website/versioned_docs/version-7.9.0/options.md @@ -47,9 +47,9 @@ Type: An object with the shape of ```flow interface CallerData { name: string; - supportsStaticESM: boolean; - supportsDynamicImport: boolean; - supportsTopLevelAwait: boolean; + supportsStaticESM?: boolean; + supportsDynamicImport?: boolean; + supportsTopLevelAwait?: boolean; } ```