Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for new 7.23.0 plugins #2828

Merged
merged 1 commit into from
Sep 25, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
75 changes: 75 additions & 0 deletions docs/plugin-proposal-import-defer.md
@@ -0,0 +1,75 @@
---
id: babel-plugin-proposal-import-defer
title: "@babel/plugin-proposal-import-defer"
sidebar_label: import-defer
---

Transforms `import defer` declarations to deferred `require()` calls.

:::caution
This plugin can only be used when also compiling modules to CommonJS.
:::

## Example
```js title="input.js"
import defer * as lib from "lib";

later(() => {
console.log(lib.value);
});
```

will be transformed to

```js title="output.js"
"use strict";

function lib(data) {
lib = () => data;
return data = _interopRequireWildcard(require("lib"));
}

later(() => {
console.log(lib().value);
});
```

## Installation

```shell npm2yarn
npm install --save-dev @babel/plugin-proposal-import-defer
```

## Usage

### With a configuration file (Recommended)

```json title="babel.config.json"
{
"plugins": [
"@babel/plugin-proposal-import-defer",
"@babel/plugin-transform-modules-commonjs"
]
}
```

### Via CLI

```sh title="Shell"
babel --plugins=@babel/plugin-proposal-import-defer,@babel/plugin-transform-modules-commonjs script.js
```

### Via Node API

```js title="JavaScript"
require("@babel/core").transformSync("code", {
plugins: [
"@babel/plugin-proposal-import-defer",
"@babel/plugin-transform-modules-commonjs"
],
});
```

## References

- [Proposal: Deferred Import Evaluation](https://github.com/tc39/proposal-defer-import-eval/)
85 changes: 85 additions & 0 deletions docs/plugin-proposal-import-source.md
@@ -0,0 +1,85 @@
---
id: babel-plugin-proposal-import-wasm-source
title: "@babel/plugin-proposal-import-wasm-source"
sidebar_label: import-wasm-source
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Transforms `import source` declarations to `WebAssembly.Module` objects, assuming that `import source` is being used to import the source of a WebAssembly Module.

The transformation applied by this plugin depends on your top-level [`targets`](https://babeljs.io/docs/options#targets) to detect whether the generated code should be compatible with Node.js, browsers, or both. When targeting Node.js, the generated code will also change depending on whether you are compiling modules to CommonJS or not.

:::caution
This plugin cannot be used when compiling modules to AMD, SystemJS, or UMD.
:::

## Example
```js title="input.js"
import source libMod from "./lib.wasm";
```

will be transformed to

<Tabs>
<TabItem value="browsers" label="Browsers" default>

```js title="output.js"
const libMod = await WebAssembly.compileStreaming(fetch(import.meta.resolve("./lib.wasm")));
```
</TabItem>
<TabItem value="node-esm" label="Node.js (ESM)">

```js title="output.js"
import { readFileSync as _readFileSync } from "fs";
const libMod = new WebAssembly.Module(_readFileSync(new URL(import.meta.resolve("./lib.wasm"))));
```
</TabItem>
<TabItem value="node-cjs" label="Node.js (CommonJS)">

```js title="output.js"
"use strict";

const libMod = new WebAssembly.Module(require("fs").readFileSync(require.resolve("./lib.wasm")));
```
</TabItem>
</Tabs>

## Installation

```shell npm2yarn
npm install --save-dev @babel/plugin-proposal-import-wasm-source
```

## Usage

### With a configuration file (Recommended)

```json title="babel.config.json"
{
"plugins": [
"@babel/plugin-proposal-import-wasm-source"
]
}
```

### Via CLI

```sh title="Shell"
babel --plugins=@babel/plugin-proposal-import-wasm-source script.js
```

### Via Node API

```js title="JavaScript"
require("@babel/core").transformSync("code", {
plugins: [
"@babel/plugin-proposal-import-wasm-source"
],
});
```

## References

- [Proposal: Source Phase Imports](https://github.com/tc39/proposal-source-phase-imports/)
62 changes: 62 additions & 0 deletions docs/plugin-proposal-optional-chaining-assign.md
@@ -0,0 +1,62 @@
---
id: babel-plugin-proposal-optional-chaining-assign
title: "@babel/plugin-proposal-optional-chaining-assign"
sidebar_label: optional-chaining
---

Transform optional chaining on the left-hand side of assignment expressions.

## Example
```js title="input.js"
function doSomething(maybeOptions) {
maybeOptions?.retries = 5;
}
```

will be transformed to

```js title="output.js"
function doSomething(maybeOptions) {
maybeOptions !== null && maybeOptions !== void 0 && maybeOptions.retries = 5;
}
```

## Installation

```shell npm2yarn
npm install --save-dev @babel/plugin-proposal-optional-chaining-assign
```

## Usage

### With a configuration file (Recommended)

```json title="babel.config.json"
{
"plugins": ["@babel/plugin-proposal-optional-chaining-assign"]
}
```

### Via CLI

```sh title="Shell"
babel --plugins @babel/plugin-proposal-optional-chaining-assign script.js
```

### Via Node API

```js title="JavaScript"
require("@babel/core").transformSync("code", {
plugins: ["@babel/plugin-proposal-optional-chaining-assign"],
});
```

## Options

### Assumptions

This plugin is affected by the [`noDocumentAll`](https://babeljs.io/docs/assumptions#nodocumentall) assumption.

## References

- [Proposal: Optional Chaining Assignment](https://github.com/tc39/proposal-optional-chaining-assignment)
44 changes: 44 additions & 0 deletions docs/plugin-syntax-import-defer.md
@@ -0,0 +1,44 @@
---
id: babel-plugin-syntax-import-defer
title: "@babel/plugin-syntax-import-defer"
sidebar_label: syntax-import-defer
---

:::note
#### Syntax only

It's unlikely you want to use this plugin directly as it only enables Babel to parse this syntax. Instead, use [plugin-proposal-import-defer](plugin-proposal-import-defer.md) to _both_ parse and transform this syntax.
:::

This plugin enables parsing for `import defer` declarations.

## Installation

```shell npm2yarn
npm install --save-dev @babel/plugin-syntax-import-defer
```

## Usage

### With a configuration file (Recommended)

```json title="babel.config.json"
{
"plugins": ["@babel/plugin-syntax-import-defer"]
}
```

### Via CLI

```sh title="Shell"
babel --plugins @babel/plugin-syntax-import-defer script.js
```

### Via Node API

```js title="JavaScript"
require("@babel/core").transformSync("code", {
plugins: ["@babel/plugin-syntax-import-defer"]
});
```

44 changes: 44 additions & 0 deletions docs/plugin-syntax-import-source.md
@@ -0,0 +1,44 @@
---
id: babel-plugin-syntax-import-source
title: "@babel/plugin-syntax-import-source"
sidebar_label: syntax-import-source
---

:::note
#### Syntax only

It's unlikely you want to use this plugin directly as it only enables Babel to parse this syntax. Instead, use [plugin-proposal-import-source](plugin-proposal-import-source.md) to _both_ parse and transform this syntax.
:::

This plugin enables parsing for `import source` declarations.

## Installation

```shell npm2yarn
npm install --save-dev @babel/plugin-syntax-import-source
```

## Usage

### With a configuration file (Recommended)

```json title="babel.config.json"
{
"plugins": ["@babel/plugin-syntax-import-source"]
}
```

### Via CLI

```sh title="Shell"
babel --plugins @babel/plugin-syntax-import-source script.js
```

### Via Node API

```js title="JavaScript"
require("@babel/core").transformSync("code", {
plugins: ["@babel/plugin-syntax-import-source"]
});
```

44 changes: 44 additions & 0 deletions docs/plugin-syntax-optional-chaining-assign.md
@@ -0,0 +1,44 @@
---
id: babel-plugin-syntax-optional-chaining-assign
title: "@babel/plugin-syntax-optional-chaining-assign"
sidebar_label: syntax-optional-chaining-assign
---

:::note
#### Syntax only

It's unlikely you want to use this plugin directly as it only enables Babel to parse this syntax. Instead, use [plugin-proposal-optional-chaining-assign](plugin-proposal-optional-chaining-assign.md) to _both_ parse and transform this syntax.
:::

This plugin enables parsing for `obj?.prop = val;` assignments.

## Installation

```shell npm2yarn
npm install --save-dev @babel/plugin-syntax-optional-chaining-assign
```

## Usage

### With a configuration file (Recommended)

```json title="babel.config.json"
{
"plugins": ["@babel/plugin-syntax-optional-chaining-assign"]
}
```

### Via CLI

```sh title="Shell"
babel --plugins @babel/plugin-syntax-optional-chaining-assign script.js
```

### Via Node API

```js title="JavaScript"
require("@babel/core").transformSync("code", {
plugins: ["@babel/plugin-syntax-optional-chaining-assign"]
});
```