Update docs for core-js 3 #1987

nicolo-ribaudo · 2019-03-14T11:33:00Z

babel-bot · 2019-03-14T11:44:01Z

Deploy preview for babel ready!

Built with commit 0a1c80e

https://deploy-preview-1987--babel.netlify.com

existentialism · 2019-03-14T13:34:52Z

docs/plugin-transform-runtime.md

@@ -88,16 +88,26 @@ require("@babel/core").transform("code", {

 ### `corejs`

-`boolean` or `number` , defaults to `false`.
+`false`, `CorejsVersion` or `{ version: CorejsVersion, proposals: boolean }`, defaults to `false`.


Can possibly reduce the first 3 lines to:

false, 2|3, or { version: 2|3, proposals: boolean }, defaults to false.

existentialism · 2019-03-14T13:36:04Z

docs/plugin-transform-runtime.md


-Specifying a number will rewrite the helpers that need polyfillable APIs to reference `core-js` instead.
+When this option is not false, all polyfillable API usages will be rewritten to reference helpers from `core-js` instead.


FWIW, I think the original sentence reads better, or maybe just:

Specifying a number will rewrite the helpers that need polyfillable APIs to reference helpers from that (major) version of core-js instead.

existentialism · 2019-03-14T13:39:57Z

docs/plugin-transform-runtime.md


-Specifying a number will rewrite the helpers that need polyfillable APIs to reference `core-js` instead.
+When this option is not false, all polyfillable API usages will be rewritten to reference helpers from `core-js` instead.
+`corejs: 2` only supports global variables (e.g. `Promise`) and static properties (e.g. `Array.from`), while `corejs: 3` also supports instance properties (e.g. `[].includes`).


Suggested change

`corejs: 2` only supports global variables (e.g. `Promise`) and static properties (e.g. `Array.from`), while `corejs: 3` also supports instance properties (e.g. `[].includes`).

Please note that `corejs: 2` only supports global variables (e.g. `Promise`) and static properties (e.g. `Array.from`), while `corejs: 3` also supports instance properties (e.g. `[].includes`).

existentialism · 2019-03-14T13:42:13Z

docs/plugin-transform-runtime.md


-This requires changing the dependency used to be [`@babel/runtime-corejs2`](runtime-corejs2.md) instead of `@babel/runtime`.
+By default, `@babel/plugin-transform-runtime` doesn't polyfill proposals. If you are using `corejs: 3`, you can opt-in using the `proposals: true` boolean flag.


Suggested change

By default, `@babel/plugin-transform-runtime` doesn't polyfill proposals. If you are using `corejs: 3`, you can opt-in using the `proposals: true` boolean flag.

By default, `@babel/plugin-transform-runtime` doesn't polyfill proposals. If you are using `corejs: 3`, you can opt into this by enabling the `proposals: true` option.

existentialism · 2019-03-14T13:43:08Z

docs/plugin-transform-runtime.md

-This requires changing the dependency used to be [`@babel/runtime-corejs2`](runtime-corejs2.md) instead of `@babel/runtime`.
+By default, `@babel/plugin-transform-runtime` doesn't polyfill proposals. If you are using `corejs: 3`, you can opt-in using the `proposals: true` boolean flag.
+
+This option requires changing the dependency used to provide the necessary runtime helpers:


Think it's too verbose to do? (On the fence, ignore if you think it's too much)

corejs option Install

false npm install --save @babel/runtime

2 npm install --save @babel/runtime-corejs2

3 npm install --save @babel/runtime-corejs3

Yeah it's better: people will only need to copy-paste

existentialism · 2019-03-14T14:05:01Z

docs/preset-env.md

@@ -302,7 +328,38 @@ var b = new Map();

 #### `useBuiltIns: false`

-Don't add polyfills automatically per file, or transform `import "@babel/polyfill"` to individual polyfills.
+Don't add polyfills automatically per file, or transform `import "core-js"` to individual polyfills.


Again, I think we should be careful about wholesale removing @babel/polyfill references as we don't want to give the impression that support is completely gone (breaking change).

existentialism · 2019-03-14T14:05:33Z

docs/preset-env.md

+
+### `corejs`
+
+`CorejsVersion` or `{ version: CorejsVersion, proposals: boolean }`, defaults to `2`.


Thoughts on making this match an earlier edit?

Suggested change

`CorejsVersion` or `{ version: CorejsVersion, proposals: boolean }`, defaults to `2`.

`2|3` or `{ version 2|3, proposals: boolean }`, defaults to `2`.

existentialism · 2019-03-14T14:06:52Z

docs/preset-env.md

+
+`corejs: 2` only supports global variables (e.g. `Promise`) and static properties (e.g. `Array.from`), while `corejs: 3` also supports instance properties (e.g. `[].includes`).
+
+By default, `@babel/plugin-transform-runtime` doesn't polyfill proposals. If you are using `corejs: 3`, you can opt-in using the `proposals: true` boolean flag:


Seems unnecessary/redundant, we mention this above?

By default, only polyfills for stable ECMAScript features are injected: if you want to polyfill them, you need to set proposals: true.

Yeah, I think I accidentally copied these last two sentences from the transform-runtime docs

existentialism · 2019-03-14T14:09:51Z

docs/preset-env.md

+`CorejsVersion` or `{ version: CorejsVersion, proposals: boolean }`, defaults to `2`.
+`CorejsVersion` can be either `2` or `3`.
+
+This option, which can only be used when `useBuiltIns` is not `false`, configures `@babel/preset-env` to inject imports to the correct `core-js` version.


Suggested change

This option, which can only be used when `useBuiltIns` is not `false`, configures `@babel/preset-env` to inject imports to the correct `core-js` version.

This option only has an effect when used alongside `useBuiltIns: usage` or `useBuiltIns: entry`, and ensures `@babel/preset-env` injects the correct imports for your `core-js` version.

existentialism · 2019-03-14T14:10:34Z

docs/preset-env.md

+`CorejsVersion` can be either `2` or `3`.
+
+This option, which can only be used when `useBuiltIns` is not `false`, configures `@babel/preset-env` to inject imports to the correct `core-js` version.
+By default, only polyfills for stable ECMAScript features are injected: if you want to polyfill them, you need to set `proposals: true`.


We should explain why proposals: true is necessary and is different than useShippedProposals (which I'm still fuzzy on, personally).

zloirock · 2019-03-18T10:32:30Z

docs/plugin-transform-runtime.md

@@ -88,17 +88,22 @@ require("@babel/core").transform("code", {

 ### `corejs`

-`boolean` or `number` , defaults to `false`.
+`false`, `2`, `3` or `{ version: 2 | 3, proposals: boolean }`, defaults to `false`.


At the top of this page a note that runtime does not support instance methods, now it's not correct.

Too many links to deprecated @babel/polyfill as a global alternative.

This page does not contain a link to core-js documentation. However, users should know what they are using. I think that we need to add it at least on the first core-js entry.

As part of this doc part I would also add a bit more clarity around how corejs works in conjunction with the corejs option from @babel/preset-env.

If both options are set to something other than false then the corejs imports will be duplicated. One for preset-env and one for transform-runtime.

A bit more clarity that if you use preset-env with corejs option you should not use the same for transform runtime will help some developer understand what is going on.

This relates to some confusion from this issue #9728.

The same info could be added to the preset-env doc also for reference.

zloirock · 2019-03-18T10:43:50Z

docs/preset-env.md

+By default, only polyfills for stable ECMAScript features are injected: if you want to polyfill them, you have three different options:
+- set the [`shippedProposals`](#shippedproposals) option to `true`. This will enable polyfills and transforms for proposal which have already been shipped in browsers for a while.
+- use `corejs: { version: 3, proposals: true }`. This will enable polyfilling of every proposal supported by `core-js`.
+- when using `useBuiltIns: "entry"`, you can directly import a [proposal polyfill](https://github.com/zloirock/core-js/tree/master/packages/core-js/proposals): `import "core-js/proposals/string-replace-all"`.


I am not sure that this is a clear enough wording. For polyfilling proposals, shippedProposals and proposals flags make sense only for usage. For entry, makes sense only the third option (and not only from proposals path - for example, import "core-js" includes import of all polyfills) without any flags.

zloirock · 2019-03-18T10:49:36Z

docs/preset-env.md

 This option configures how `@babel/preset-env` handles polyfills.

+When either the `usage` or `entry` options are used, `@babel-preset-env` will add direct references to `core-js` modules as bare imports (or requires). This means `core-js` will be resolved relative to the file itself and needs to be accessible.
+


The same as in runtime docs - I don't see any links to core-js documentation in this file.

Built-ins link in include should be updated.

zloirock · 2019-03-18T10:55:11Z

docs/preset-env.md

@@ -372,7 +414,8 @@ The following are currently supported:

 **Builtins**

- [es7.array.flat-map](https://github.com/tc39/proposal-flatMap)
+- [esnext.global-this](https://github.com/tc39/proposal-global) (only supported by `core-js@3`)
+- [esnext.string.match-all](https://github.com/tc39/proposal-string-matchall) (only supported by `core-js@3`)


Makes sense specify that will be injected only with useBuiltIns: usage.

docs/preset-env.md

zloirock · 2019-03-20T00:55:53Z

Seems also need to update preset-env options in the repl.

Co-Authored-By: nicolo-ribaudo <nicolo.ribaudo@gmail.com>

nstepien

Found a typo.

nstepien · 2019-03-20T13:40:35Z

docs/polyfill.md

+> 🚨 As of Babel 7.4.0, this package has been deprecated in favor of directly including `core-js/stable` (to polyfill ECMAScript features) and `regenerator-runtime/runtime` (needed to use transpiled generator functions):
+> ```js
+> import "core-js/stable";
+> import "renegerator-runtime/runtime";


regenerator-runtime instead of renegerator-runtime 🙂

docs/polyfill.md

Co-Authored-By: nicolo-ribaudo <nicolo.ribaudo@gmail.com>

nicolo-ribaudo · 2019-04-09T15:16:56Z

I'm merging this PR with only one ✔️ since a lot of users are confused by the option not mentioned in the docs. If it needs to be changed it can be done in a folow-up PR.

Update docs for core-js 3

9c3c54f

nicolo-ribaudo added the docs label Mar 14, 2019

nicolo-ribaudo requested a review from zloirock March 14, 2019 11:33

Update

17c4a13

existentialism reviewed Mar 14, 2019

View reviewed changes

Address review by Brian

f3af976

zloirock reviewed Mar 18, 2019

View reviewed changes

Review by Denis

a93b7cf

zloirock approved these changes Mar 18, 2019

View reviewed changes

danez reviewed Mar 19, 2019

View reviewed changes

docs/preset-env.md Outdated Show resolved Hide resolved

Update docs/preset-env.md

dcbd3d3

Co-Authored-By: nicolo-ribaudo <nicolo.ribaudo@gmail.com>

nstepien suggested changes Mar 20, 2019

View reviewed changes

nstepien reviewed Mar 20, 2019

View reviewed changes

docs/polyfill.md Outdated Show resolved Hide resolved

Update docs/polyfill.md

0a1c80e

Co-Authored-By: nicolo-ribaudo <nicolo.ribaudo@gmail.com>

zloirock mentioned this pull request Mar 27, 2019

Core-JS imports are duplicated between core-js@3 and core-js-pure@3 babel/babel#9728

Closed

nicolo-ribaudo mentioned this pull request Mar 27, 2019

Tweak preset-env corejs/useBuiltIns warning and error messages babel/babel#9716

Merged

zloirock mentioned this pull request Apr 2, 2019

core-js@3, babel and a look into the future zloirock/core-js#496

Closed

nicolo-ribaudo merged commit d860a49 into babel:master Apr 9, 2019

nicolo-ribaudo deleted the core-js-3 branch April 9, 2019 15:17

existentialism added the needs backport label Jul 10, 2019

existentialism mentioned this pull request Jul 10, 2019

Create 7.5.0 docs #2058

Merged

existentialism removed needs backport labels Jul 11, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs for core-js 3 #1987

Update docs for core-js 3 #1987

nicolo-ribaudo commented Mar 14, 2019

babel-bot commented Mar 14, 2019 •

edited

Loading

existentialism Mar 14, 2019

existentialism Mar 14, 2019

existentialism Mar 14, 2019

existentialism Mar 14, 2019

existentialism Mar 14, 2019 •

edited

Loading

nicolo-ribaudo Mar 14, 2019

existentialism Mar 14, 2019

existentialism Mar 14, 2019

existentialism Mar 14, 2019

nicolo-ribaudo Mar 14, 2019

existentialism Mar 14, 2019

existentialism Mar 14, 2019

zloirock Mar 18, 2019

radum Mar 27, 2019 •

edited

Loading

zloirock Mar 18, 2019 •

edited

Loading

zloirock Mar 18, 2019

zloirock Mar 18, 2019

zloirock Mar 18, 2019 •

edited

Loading

zloirock commented Mar 20, 2019

nstepien left a comment

nstepien Mar 20, 2019

nicolo-ribaudo commented Apr 9, 2019


		Specifying a number will rewrite the helpers that need polyfillable APIs to reference `core-js` instead.
		When this option is not false, all polyfillable API usages will be rewritten to reference helpers from `core-js` instead.

	`corejs: 2` only supports global variables (e.g. `Promise`) and static properties (e.g. `Array.from`), while `corejs: 3` also supports instance properties (e.g. `[].includes`).
	Please note that `corejs: 2` only supports global variables (e.g. `Promise`) and static properties (e.g. `Array.from`), while `corejs: 3` also supports instance properties (e.g. `[].includes`).


		This requires changing the dependency used to be [`@babel/runtime-corejs2`](runtime-corejs2.md) instead of `@babel/runtime`.
		By default, `@babel/plugin-transform-runtime` doesn't polyfill proposals. If you are using `corejs: 3`, you can opt-in using the `proposals: true` boolean flag.

`corejs` option	Install
`false`	`npm install --save @babel/runtime`
`2`	`npm install --save @babel/runtime-corejs2`
`3`	`npm install --save @babel/runtime-corejs3`


		### `corejs`

		`CorejsVersion` or `{ version: CorejsVersion, proposals: boolean }`, defaults to `2`.

	`CorejsVersion` or `{ version: CorejsVersion, proposals: boolean }`, defaults to `2`.
	`2\|3` or `{ version 2\|3, proposals: boolean }`, defaults to `2`.

	This option, which can only be used when `useBuiltIns` is not `false`, configures `@babel/preset-env` to inject imports to the correct `core-js` version.
	This option only has an effect when used alongside `useBuiltIns: usage` or `useBuiltIns: entry`, and ensures `@babel/preset-env` injects the correct imports for your `core-js` version.

		This option configures how `@babel/preset-env` handles polyfills.

		When either the `usage` or `entry` options are used, `@babel-preset-env` will add direct references to `core-js` modules as bare imports (or requires). This means `core-js` will be resolved relative to the file itself and needs to be accessible.

Update docs for core-js 3 #1987

Update docs for core-js 3 #1987

Conversation

nicolo-ribaudo commented Mar 14, 2019

babel-bot commented Mar 14, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

existentialism Mar 14, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

radum Mar 27, 2019 • edited Loading

Choose a reason for hiding this comment

zloirock Mar 18, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zloirock Mar 18, 2019 • edited Loading

Choose a reason for hiding this comment

zloirock commented Mar 20, 2019

nstepien left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nicolo-ribaudo commented Apr 9, 2019

babel-bot commented Mar 14, 2019 •

edited

Loading

existentialism Mar 14, 2019 •

edited

Loading

radum Mar 27, 2019 •

edited

Loading

zloirock Mar 18, 2019 •

edited

Loading

zloirock Mar 18, 2019 •

edited

Loading