diff --git a/docs/faq.md b/docs/faq.md index 905babe94b..216fdd81c7 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -50,7 +50,7 @@ interop issues. We hear you! Babel 6 requires a tiny bit of configuration in order to get going. [We think this is for the best](/blog/2015/10/29/6.0.0) and have added -[presets](plugins.md#presets) to ease this transition. +[presets](presets.md) to ease this transition. ## Upgrading from Babel 5.x to Babel 6 diff --git a/docs/helper-compilation-targets.md b/docs/helper-compilation-targets.md index 43392d836c..91f418de63 100644 --- a/docs/helper-compilation-targets.md +++ b/docs/helper-compilation-targets.md @@ -151,7 +151,7 @@ Normalize user specified `targets` to a list of supported targets. See also (`@b getTargets(); ``` -An empty compilation target is equivalent to [force all transforms](preset-env.md#forceAllTransforms). The default compilation targets will be changed to browserlists query [`defaults, not IE 11`](https://runkit.com/jlhwung/605cd58b2c44c6001a463717) in Babel 8. +An empty compilation target is equivalent to [force all transforms](preset-env.md#forcealltransforms). The default compilation targets will be changed to browserlists query [`defaults, not IE 11`](https://runkit.com/jlhwung/605cd58b2c44c6001a463717) in Babel 8. One can also query the compilation targets with ES Module support, like [`@vue/babel-preset-app`](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app) did in order to provide a set of modern targets. diff --git a/docs/index.md b/docs/index.md index 3685e14ec6..23918139dd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -105,7 +105,7 @@ Learn more about [Flow](https://flow.org/) and [TypeScript](https://www.typescri ## Pluggable -Babel is built out of plugins. Compose your own transformation pipeline using existing plugins or write your own. Easily use a set of plugins by using or creating a [preset](plugins.md#presets). [Learn more โ†’](plugins.md) +Babel is built out of [plugins](plugins.md). Compose your own transformation pipeline using existing plugins or write your own. Easily use a set of plugins by using or creating a [preset](presets.md). Create a plugin on the fly with [astexplorer.net](https://astexplorer.net/#/KJ8AjD6maa) or use [generator-babel-plugin](https://github.com/babel/generator-babel-plugin) to generate a plugin template. diff --git a/docs/plugin-transform-runtime.md b/docs/plugin-transform-runtime.md index 0c69771511..f0a34e56e2 100644 --- a/docs/plugin-transform-runtime.md +++ b/docs/plugin-transform-runtime.md @@ -80,7 +80,13 @@ With options (and their defaults): } ``` +:::babel8 +The plugin assumes that all polyfillable APIs will be provided by the user. See [babel-polyfills](https://github.com/babel/babel-polyfills) for more information. +::: + +:::babel7 The plugin defaults to assuming that all polyfillable APIs will be provided by the user. Otherwise the [`corejs`](#corejs) option needs to be specified. +::: ### Via CLI @@ -182,8 +188,12 @@ This option controls which package of helpers `@babel/plugin-transform-runtime` - `babel-plugin-polyfill-corejs2` suggests `@babel/runtime-corejs2` - Fallback to `@babel/runtime` +:::babel7 + Note that specifying the [`corejs`](#corejs) option will internally enable the corresponding `babel-plugin-polyfill-corejs*` plugin, thus it has an effect on the final module name. +::: + ::::babel7 ### `regenerator` diff --git a/docs/plugins.md b/docs/plugins.md index 185270e049..58a165c827 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -5,8 +5,6 @@ title: Plugins Babel's code transformations are enabled by applying plugins (or [presets](presets.md)) to your [configuration file](config-files.md). -
- ## Using a Plugin If the plugin is on [npm](https://www.npmjs.com/search?q=babel-plugin), you can pass in the name of the plugin and Babel will check that it's installed in `node_modules`. This is added to the [plugins](options.md#presets) config option, which takes an array. diff --git a/docs/preset-env-standalone.md b/docs/preset-env-standalone.md index 4cf8cf5559..7c5757dc97 100644 --- a/docs/preset-env-standalone.md +++ b/docs/preset-env-standalone.md @@ -5,7 +5,7 @@ sidebar_label: env-standalone --- :::danger -๐Ÿšจ As of Babel 7.8.0, this package has been deprecated. It is now included in [@babel/standalone](standalone.md#usage). +๐Ÿšจ As of Babel 7.8.0, this package has been deprecated. It is now included in [@babel/standalone](standalone.md). ::: # Installation diff --git a/docs/preset-env.md b/docs/preset-env.md index 1f45ac48b7..23bf75bc67 100644 --- a/docs/preset-env.md +++ b/docs/preset-env.md @@ -398,7 +398,7 @@ By default, only polyfills for stable ECMAScript features are injected: if you w
Example -With Babel 7's [JavaScript config file](config-files#javascript) support, you can force all transforms to be run if env is set to `production`. +With Babel 7's [JavaScript config file](config-files.md#supported-file-extensions) support, you can force all transforms to be run if env is set to `production`. ```js title="babel.config.js" module.exports = function(api) { diff --git a/docs/preset-react.md b/docs/preset-react.md index 81b6a87c9e..3a5b1e6306 100644 --- a/docs/preset-react.md +++ b/docs/preset-react.md @@ -137,7 +137,7 @@ Decides which runtime to use. This toggles behavior specific to development, such as adding `__source` and `__self`. -This is useful when combined with the [env option](options.md#env) configuration or [js config files](config-files.md#javascript). +This is useful when combined with the [env option](options.md#env) configuration or [js config files](config-files.md#supported-file-extensions). :::babel8 diff --git a/docs/v8-migration-api.md b/docs/v8-migration-api.md index 68d8de843f..a6a4cf4d74 100644 --- a/docs/v8-migration-api.md +++ b/docs/v8-migration-api.md @@ -3,6 +3,8 @@ title: "Upgrade to Babel 8 (API)" id: v8-migration-api --- +import Link from '@docusaurus/Link'; + This document lists the breaking changes introduced in Babel 8.0.0, and how to adapt your usage of Babel to them when upgrading from Babel 7.0.0. This document is intended for developers using Babel's API directly, such as Babel plugin authors, or authors of projects that use Babel as a library. @@ -45,7 +47,7 @@ Check out the [Babel 8 migration guide](v8-migration.md) first to learn about us ![medium](https://img.shields.io/badge/risk%20of%20breakage%3F-medium-yellow.svg) -- Use `bigint` for `BigIntLiteral.value`, rather than a string([#17378](https://github.com/babel/babel/pull/17378)) +- Use `bigint` for `BigIntLiteral.value`, rather than a string([#17378](https://github.com/babel/babel/pull/17378)) ```js // Example input @@ -81,7 +83,7 @@ Most of the changes to our TypeScript-specific AST nodes are to reduce the diffe ![medium](https://img.shields.io/badge/risk%20of%20breakage%3F-medium-yellow.svg) -- Use an identifier for `TSTypeParameter.name`, rather than a plain string ([#12829](https://github.com/babel/babel/pull/12829)) +- Use an identifier for `TSTypeParameter.name`, rather than a plain string ([#12829](https://github.com/babel/babel/pull/12829)) ```ts title="input.ts" // T is a TSTypeParameter @@ -332,7 +334,7 @@ Most of the changes to our TypeScript-specific AST nodes are to reduce the diffe
-- Rename `typeParameters` to `typeArguments` in `CallExpression`, `JSXOpeningElement`, `NewExpression`, `OptionalCallExpression`, `TSImportType`, `TSInstantiationExpression`, `TSTypeQuery` and `TSTypeReference` ([#16679](https://github.com/babel/babel/issues/16679), [#17008](https://github.com/babel/babel/pull/17008), [#17012](https://github.com/babel/babel/pull/17012), [#17020](https://github.com/babel/babel/pull/17020), [#17042](https://github.com/babel/babel/pull/17042)) +- Rename `typeParameters` to `typeArguments` in `CallExpression`, `JSXOpeningElement`, `NewExpression`, `OptionalCallExpression`, `TSImportType`, `TSInstantiationExpression`, `TSTypeQuery` and `TSTypeReference` ([#16679](https://github.com/babel/babel/issues/16679), [#17008](https://github.com/babel/babel/pull/17008), [#17012](https://github.com/babel/babel/pull/17012), [#17020](https://github.com/babel/babel/pull/17020), [#17042](https://github.com/babel/babel/pull/17042))
CallExpression @@ -645,7 +647,7 @@ Most of the changes to our TypeScript-specific AST nodes are to reduce the diffe } ``` -- Split `typeParameter` of `TSMappedType` ([#16733](https://github.com/babel/babel/pull/16733)). +- Split `typeParameter` of `TSMappedType` ([#16733](https://github.com/babel/babel/pull/16733)). In `TSMappedType` nodes, the `typeParameter` property is flattened as `key` and `constraint` properties of `TSMappedType` itself. @@ -826,7 +828,7 @@ Most of the changes to our TypeScript-specific AST nodes are to reduce the diffe } ``` -- Wrap the `members` of `TSEnumDeclaration` within a `TSEnumBody` node ([#16979](https://github.com/babel/babel/pull/16979)) +- Wrap the `members` of `TSEnumDeclaration` within a `TSEnumBody` node ([#16979](https://github.com/babel/babel/pull/16979)) ```ts title="input.ts" // Example input @@ -1482,7 +1484,7 @@ Other than the changes listed below, `@babel/parser` is affected by all the [AST This change also affects the `isRequired` function of `@babel/helper-compilation-targets`, which receives plugin names as its first parameter. - __Migration__: For example, use `transform-class-properties` rather than `proposal-class-properties`. For a complete list of renamed plugin, see [Packages Renames section of Babel 8 migration](./v8-migration.md#package-renames). + __Migration__: For example, use `transform-class-properties` rather than `proposal-class-properties`. For a complete list of renamed plugin, see [Packages Renames section of Babel 8 migration](./v8-migration.md#renamed-packages). ```diff title="my-babel-plugin.js" module.exports = api => { diff --git a/docs/v8-migration.md b/docs/v8-migration.md index 023b31126e..217e96f38d 100644 --- a/docs/v8-migration.md +++ b/docs/v8-migration.md @@ -3,6 +3,8 @@ title: "Upgrade to Babel 8" id: v8-migration --- +import Link from '@docusaurus/Link'; + This document lists the breaking changes introduced in Babel 8.0.0, and how to adapt your usage of Babel to them when upgrading from Babel 7.0.0. If you are working directly with Babel's API (because, for example, you maintain a custom Babel plugin), please also check the [migration guide for integration](./v8-migration-api.md). @@ -20,10 +22,10 @@ You should read this full document to understand what options you need to change - If you are not using a `.browserslistrc` file, define a top-level [`targets`](./options.md#targets) option. Babel 7 defaults to `targets: ">= 0%"` (all browsers), while Babel 8 defaults to [`targets: "defaults"`](https://browsersl.ist/#q=defaults). If you are using [`@babel/preset-env`'s `targets`](./preset-env.md#targets) option, copy its value to the top-level configuration (next to `presets`). - If you use `@babel/preset-env`, enable its [`bugfixes`](./preset-env.md#bugfixes) option. - If you use `@babel/preset-env`'s `loose` or `spec` options, [migrate to `assumptions`](./assumptions.md#migrating-from-babelpreset-envs-loose-and-spec-modes). Consider migrating also if you are using `loose` or `spec` in individual plugins, althought they still work in Babel 8. -- If you use `@babel/preset-react` or `@babel/plugin-transform-react-jsx`, explicitly set their [`runtime`](./preset-react.md#runtime) option (Babel 7 defaults to `"classic"`, Babel 8 to `"automatic"`). If you keep using the classic runtime, set the [`useSpread`](./plugin-transform-react-jsx.md#usespread) option to `true`. +- If you use `@babel/preset-react` or `@babel/plugin-transform-react-jsx`, explicitly set their [`runtime`](./preset-react.md#runtime) option (Babel 7 defaults to `"classic"`, Babel 8 to `"automatic"`). If you keep using the classic runtime, set the `useSpread` option to `true`. - If you use the TypeScript or Flow presets, replace the `isTSX` and `allExtensions` options with [`ignoreExtensions`](#babel-preset-typescript). - If you are transforming TypeScript or Flow, set the `allowDeclareFields` option to `true` (see [TypeScript](./preset-typescript.md#allowdeclarefields)). -- If you use [`@babel/plugin-transform-runtime`'s `corejs`](./plugin-transform-runtime.md#corejs) or [`@babel/preset-env`'s `useBuiltIns`](./preset-env.md#usebuiltins) options, remove them and use [`babel-plugin-polyfill-corejs3`](https://github.com/babel/babel-polyfills/tree/main/packages/babel-plugin-polyfill-corejs3) instead. +- If you use `@babel/plugin-transform-runtime`'s `corejs` or [`@babel/preset-env`'s `useBuiltIns`](./preset-env.md#usebuiltins) options, remove them and use [`babel-plugin-polyfill-corejs3`](https://github.com/babel/babel-polyfills/tree/main/packages/babel-plugin-polyfill-corejs3) instead. - If you use `@babel/plugin-proposal-decorators`, set its [`version`](./plugin-proposal-decorators.md#version) option to `legacy` or `2023-11`. - Remove the `@babel/plugin-proposal-record-and-tuple` and `@babel/plugin-syntax-import-assertions` plugins if you are using them. @@ -82,8 +84,8 @@ The following packages has been renamed from `...-proposal-...` to `...-transfor `core-js@2` has not been maintained for years, and you should switch to `core-js@3` instead. -Please upgrade to `@babel/runtime-corejs3` ([#11751](https://github.com/babel/babel/issues/10746#issuecomment-573402372)). After -you install the new runtime, please set the [`corejs` version](./plugin-transform-runtime.md#corejs) to the `core-js` version that you are using. +Please upgrade to `babel-plugin-polyfill-corejs3`. After +you install the new runtime, please set the [`corejs` version](https://github.com/babel/babel-polyfills/tree/main/packages/babel-plugin-polyfill-corejs3#version) to the `core-js` version that you are using. ```diff title="babel.config.json" { @@ -697,7 +699,7 @@ Make sure to also check the [@babel/plugin-transform-flow-strip-types](#babel-pl ![medium](https://img.shields.io/badge/risk%20of%20breakage%3F-medium-yellow.svg) -- Only support the `legacy` and `2023-11` versions of the proposal. In addition to that, the plugin now requires a [`version`](./plugin-proposal-decorators.md#version) option ([#12712](https://github.com/babel/babel/pull/12712), [#15676](https://github.com/babel/babel/pull/15676)) +- Only support the `legacy` and `2023-11` versions of the proposal. In addition to that, the plugin now requires a [`version`](./plugin-proposal-decorators.md#version) option ([#12712](https://github.com/babel/babel/pull/12712), [#15676](https://github.com/babel/babel/pull/15676)) **Migration**: You should migrate to the [latest version of the proposal](https://github.com/tc39/proposal-decorators/), `"2023-11"`. @@ -725,7 +727,7 @@ Make sure to also check the [@babel/plugin-transform-flow-strip-types](#babel-pl ![medium](https://img.shields.io/badge/risk%20of%20breakage%3F-medium-yellow.svg) -- Only support the `fsharp` and `hack` proposals ([#17732](https://github.com/babel/babel/pull/17732)) +- Only support the `fsharp` and `hack` proposals ([#17732](https://github.com/babel/babel/pull/17732)) **Migration**: If you used `smart` or `minimal` proposal, you should migrate to either the `fsharp` or the `hack` [proposal](./plugin-proposal-pipeline-operator.md#usage). diff --git a/website/blog/2015-02-23-babel-loves-react.md b/website/blog/2015-02-23-babel-loves-react.md index 7cc7321722..a3598e13a7 100644 --- a/website/blog/2015-02-23-babel-loves-react.md +++ b/website/blog/2015-02-23-babel-loves-react.md @@ -18,7 +18,7 @@ Let me show you just how easy it is to switch: > here. If you'd like to see a more complete list check out our > [Using Babel](/setup) page. -**In the Browser** ([docs](/setup#browser/)) +**In the Browser** ([docs](/setup#browser)) Before: @@ -46,7 +46,7 @@ After: $ browserify -t babelify main.js ``` -**In Node** ([docs](/setup#require/)) +**In Node** ([docs](/setup#babel_register)) Before: @@ -102,7 +102,7 @@ The list goes on, but you probably get how simple it is by now. If you didn't see the tool you are looking for don't worry we have a full list of them on our [Using Babel](/setup) page. -If you need more help getting setup be sure to read our [JSX](/setup#jsx/) +If you need more help getting setup be sure to read our [JSX](/docs/#jsx-and-react) docs or come ask other Babel users in our [support chat](https://gitter.im/babel/babel). diff --git a/website/blog/2015-03-31-5.0.0.md b/website/blog/2015-03-31-5.0.0.md index 1035718b74..170cb4b021 100644 --- a/website/blog/2015-03-31-5.0.0.md +++ b/website/blog/2015-03-31-5.0.0.md @@ -7,6 +7,8 @@ categories: announcements share_text: "5.0.0 Released" --- +import Link from "@docusaurus/Link"; + In the past few months Babel has been welcomed into several major communities such as Node, React, Ember, Backbone, Angular, Rails, and many others. We launched the [Users page](/users) only a few weeks ago and it's really cool to @@ -83,11 +85,11 @@ Now let's dive into the changes we made to 5.0. - [Removed Features](#removed-features) - [imports are now hoisted](#imports-are-now-hoisted) -

New Features

+

New Features

## New Proposals -### Stage 0: Class Properties +### Stage 0: Class Properties { /*#stage-0:-class-properties*/ } [Jeff Morrison's](https://github.com/jeffmo) stage 0 [class property initializers proposal](https://gist.github.com/jeffmo/054df782c05639da2adb) @@ -123,7 +125,7 @@ $ babel --optional es7.classProperties script.js $ babel --stage 0 script.js ``` -### Stage 1: Decorators +### Stage 1: Decorators { /*#stage-1:-decorators*/ } [Yehuda Katz'](https://github.com/wycats) stage 1 [decorators proposal](https://github.com/wycats/javascript-decorators) allows @@ -194,7 +196,7 @@ $ babel --optional es7.decorators script.js $ babel --stage 1 script.js ``` -### Stage 1: Export Extensions +### Stage 1: Export Extensions { /*#stage-1:-export-extensions*/ } [Lee Byron's](https://github.com/leebyron) stage 1 [additional export-from statements proposal](https://github.com/leebyron/ecmascript-more-export-from) @@ -362,13 +364,13 @@ See the [docs](/docs/options) for more info. into the powerful traversal and transformation internals of Babel. See the [docs](/docs/plugins) for more info. -

Breaking Changes

+

Breaking Changes

### Experimental Option The `experimental` option has been **removed**. Fear not though, there is a replacement. Babel now categories the ES7 transformers by -[TC39 stages](#tc39-changes). +[TC39 stages](#tc39-process). tl;dr If you're using the `experimental` option, simply change it to `$ babel --stage 0` or `{ stage: 0 }`. diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index e242fb8f4e..9a59e0599b 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -142,15 +142,15 @@ function docusaurusReplRoutePlugin() { const siteConfig: Config = { future: { - // See https://docusaurus.io/blog/releases/3.6 - experimental_faster: true, v4: { + fasterByDefault: true, removeLegacyPostBuildHeadAttribute: true, }, }, titleDelimiter: "ยท", baseUrl: "/", favicon: "img/favicon.png", + onBrokenAnchors: "throw", onBrokenLinks: "throw", customFields: { repoUrl: "https://github.com/babel/babel", diff --git a/website/src/pages/setup.tsx b/website/src/pages/setup.tsx index 7f8c544e81..7a176da3eb 100644 --- a/website/src/pages/setup.tsx +++ b/website/src/pages/setup.tsx @@ -1,6 +1,7 @@ import React, { useState } from "react"; import Link from "@docusaurus/Link"; import Layout from "@theme/Layout"; +import useBrokenLinks from '@docusaurus/useBrokenLinks'; import useDocusaurusContext from "@docusaurus/useDocusaurusContext"; import Translate from "@docusaurus/Translate"; import MarkdownBlock from "../components/v1/MarkdownBlock"; @@ -34,10 +35,13 @@ const SetupSelectButton = (props) => { const className = "button button--secondary" + (tool === activeTool ? " button--active" : ""); + const href = "#" + tool; + // Collect the tools as anchor here because StepInstallAndUsage will only render the selected tool. + useBrokenLinks().collectAnchor(tool); return ( props.onSelectTool(tool)} > @@ -108,9 +112,11 @@ const StepInstallAndUsage = (props) => { Usage ); + const id = props.name === "install" ? props.tool : `${props.tool}-usage`; return (