docs: clarify modules option in preset-env

[JLHwung]

{ modules: false } has been long used as a fast switch to "preserve ES module" so bundlers can leverage from the module syntax. However the defaults { modules: "auto" } should be preferred because it reads caller support data and reduces cognitive loads -- Idea like "I want to disable module transforms so Webpack can do tree shaking" is not straightforward, it is the defaults that should work out of that for you.

Since Babel 7.11, preset-env will assume { modules: false } as to "preserve ES module" and the compiled code will be served without bundling. By doing so preset-env can determine whether it should transpile export * as ns based on the targets. This assumption only works when it is not passed to bundlers, where bundlers may not support latest module syntax, (e.g. Webpack 5.0.0-beta.21 supports this recently, thus export * as ns will break on Webpack 4.

Although export * as ns will break on Webpack 4, since it is not included in preset-env before, users should have supplied @babel/plugin-proposal-export-namesapce-from so they are good when upgrading to Babel 7.11. However users just begin to use export * as ns in preset-env 7.11 with

{
  presets: ["@babel/preset-env", {
    modules: false,
    targets: { browsers: "latest Chrome 2 versions" }
  }]
}

may surprisedly find that preset-env does not transpile export * as ns and errors are thrown from Webpack.

[netlify]

Deploy preview for babel ready!

Built without sensitive environment variables with commit 17d14a5

https://deploy-preview-2301--babel.netlify.app

[nicolo-ribaudo]

Suggested change

	supportsStaticESM: boolean;
	supportsDynamicImport: boolean;
	supportsTopLevelAwait: boolean;
	}
	supportsStaticESM?: boolean;
	supportsDynamicImport?: boolean;
	supportsTopLevelAwait?: boolean;
	}

These should all be optional