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.

Sign up for GitHub

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

Jump to bottom

Ad docs for import attributes #2780

Merged
merged 4 commits into from May 26, 2023
Merged

Ad docs for import attributes #2780

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7d20795
Ad docs for import attributes
nicolo-ribaudo May 8, 2023
0c24e6c
Add `deprecatedAssertSyntax` default value
nicolo-ribaudo May 22, 2023
5ca13f9
Add to sidebar
nicolo-ribaudo May 22, 2023
8561e1a
Merge branch 'main' into import-attr-docs
nicolo-ribaudo May 26, 2023
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
34 changes: 18 additions & 16 deletions docs/generator.md
View file
Open in desktop
Expand Up @@ -38,27 +38,29 @@ const output = generate(

| Version | Changes |
| --- | --- |
| v7.22.0 | Added `importAttributesKeyword` |
| v7.21.0 | Added `inputSourceMap` |
</details>

Options for formatting output:

| name | type | default | description |
| ---------------------- | ------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| auxiliaryCommentAfter | string | | Optional string to add as a block comment at the end of the output file |
| auxiliaryCommentBefore | string | | Optional string to add as a block comment at the start of the output file |
| comments | boolean | `true` | Should comments be included in output |
| compact | boolean or `'auto'` | `opts.minified` | Set to `true` to avoid adding whitespace for formatting |
| concise | boolean | `false` | Set to `true` to reduce whitespace (but not as much as `opts.compact`) |
| decoratorsBeforeExport | boolean | | Set to `true` to print decorators before `export` in output. |
| filename | string | | Used in warning messages |
| jsescOption | object | | Use `jsesc` to process literals. `jsesc` is applied to numbers only if `jsescOption.numbers` (added in `v7.9.0`) is present. You can customize `jsesc` by [passing options](https://github.com/mathiasbynens/jsesc#api) to it. |
| jsonCompatibleStrings | boolean | `false` | Set to true to run `jsesc` with "json": true to print "\u00A9" vs. "©"; |
| minified | boolean | `false` | Should the output be minified |
| retainFunctionParens | boolean | `false` | Retain parens around function expressions (could be used to change engine parsing behavior) |
| retainLines | boolean | `false` | Attempt to use the same line numbers in the output code as in the source code (helps preserve stack traces) |
| shouldPrintComment | function | `opts.comments` | Function that takes a comment (as a string) and returns `true` if the comment should be included in the output. By default, comments are included if `opts.comments` is `true` or if `opts.minified` is `false` and the comment contains `@preserve` or `@license` |
| topicToken | `'%'` or `'#'` | | The token to use with [Hack-pipe topic references](plugin-proposal-pipeline-operator.md). This is required when there are any `TopicReference` nodes.
| name | type | default | description |
| ----------------------- | ------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| auxiliaryCommentAfter | string | | Optional string to add as a block comment at the end of the output file |
| auxiliaryCommentBefore | string | | Optional string to add as a block comment at the start of the output file |
| comments | boolean | `true` | Should comments be included in output |
| compact | boolean or `'auto'` | `opts.minified` | Set to `true` to avoid adding whitespace for formatting |
| concise | boolean | `false` | Set to `true` to reduce whitespace (but not as much as `opts.compact`) |
| decoratorsBeforeExport | boolean | | Set to `true` to print decorators before `export` in output. |
| filename | string | | Used in warning messages |
| importAttributesKeyword | `"with"`, `"assert"`, or `"with-legacy"` | | The import attributes/assertions syntax to use. `"with"` for `import "..." with { type: "json" }`, `"assert"` for `import "..." assert { type: "json" }`, and `"with-legacy"` for `import "..." with type: "json"`. When not specified, `@babel/generator` will try to match the style in the input code based on the AST shape. |
| jsescOption | object | | Use `jsesc` to process literals. `jsesc` is applied to numbers only if `jsescOption.numbers` (added in `v7.9.0`) is present. You can customize `jsesc` by [passing options](https://github.com/mathiasbynens/jsesc#api) to it. |
| jsonCompatibleStrings | boolean | `false` | Set to true to run `jsesc` with "json": true to print "\u00A9" vs. "©"; |
| minified | boolean | `false` | Should the output be minified |
| retainFunctionParens | boolean | `false` | Retain parens around function expressions (could be used to change engine parsing behavior) |
| retainLines | boolean | `false` | Attempt to use the same line numbers in the output code as in the source code (helps preserve stack traces) |
| shouldPrintComment | function | `opts.comments` | Function that takes a comment (as a string) and returns `true` if the comment should be included in the output. By default, comments are included if `opts.comments` is `true` or if `opts.minified` is `false` and the comment contains `@preserve` or `@license` |
| topicToken | `'%'` or `'#'` | | The token to use with [Hack-pipe topic references](plugin-proposal-pipeline-operator.md). This is required when there are any `TopicReference` nodes.

Options for source maps:

Expand Down
14 changes: 10 additions & 4 deletions docs/parser.md
View file
Open in desktop
Expand Up @@ -211,7 +211,7 @@ require("@babel/parser").parse("code", {

| Version | Changes |
| --- | --- |
| `v7.22.0` | Enabled `regexpUnicodeSets` by default |
| `v7.22.0` | Enabled `regexpUnicodeSets` by default, added `importAttributes` |
| `v7.20.0` | Added `explicitResourceManagement`, `importReflection` |
| `v7.17.0` | Added `regexpUnicodeSets`, `destructuringPrivate`, `decoratorAutoAccessors` |
| `v7.15.0` | Added `hack` to the `proposal` option of `pipelineOperator`. Moved `topLevelAwait`, `privateIn` to Latest ECMAScript features |
Expand All @@ -230,16 +230,16 @@ require("@babel/parser").parse("code", {
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `asyncDoExpressions` ([proposal](https://github.com/tc39/proposal-async-do-expressions)) | `async do { await requestAPI().json() }` |
| `decimal` ([proposal](https://github.com/tc39/proposal-decimal)) | `0.3m` |
| `decorators` ([proposal](https://github.com/tc39/proposal-decorators)) <br/> `decorators-legacy` | `@a class A {}` |
| `decorators` ([proposal](https://github.com/tc39/proposal-decorators)) <br/> `decorators-legacy` | `@a class A {}` |
| `decoratorAutoAccessors` ([proposal](https://github.com/tc39/proposal-decorators)) | `class Example { @reactive accessor myBool = false; }` |
| `destructuringPrivate` ([proposal](https://github.com/tc39/proposal-destructuring-private)) | `class Example { #x = 1; method() { const { #x: x } = this; } }` |
| `doExpressions` ([proposal](https://github.com/tc39/proposal-do-expressions)) | `var a = do { if (true) { 'hi'; } };` |
| `explicitResourceManagement` ([proposal](https://github.com/tc39/proposal-explicit-resource-management)) | `using reader = getReader()` |
| `exportDefaultFrom` ([proposal](https://github.com/tc39/ecmascript-export-default-from)) | `export v from "mod"` |
| `functionBind` ([proposal](https://github.com/zenparsing/es-function-bind)) | `a::b`, `::console.log` |
| `functionSent` ([proposal](https://github.com/tc39/proposal-function.sent)) | `function.sent` |
| `importAssertions` ([proposal](https://github.com/tc39/proposal-import-assertions)) | `import json from "./foo.json" assert { type: "json" };` |
| `importReflection` ([proposal](https://github.com/tc39/proposal-import-reflection)) | `import module foo from "./foo.wasm";` |
| `importAttributes` ([proposal](https://github.com/tc39/proposal-import-attributes)) <br/> `importAssertions` (⚠️ deprecated) | `import json from "./foo.json" with { type: "json" };` |
| `importReflection` ([proposal](https://github.com/tc39/proposal-import-reflection)) | `import module foo from "./foo.wasm";` |
| `moduleBlocks` ([proposal](https://github.com/tc39/proposal-js-module-blocks)) | `let m = module { export let y = 1; };` |
| `partialApplication` ([proposal](https://github.com/babel/proposals/issues/32)) | `f(?, a)` |
| `pipelineOperator` ([proposal](https://github.com/babel/proposals/issues/29)) | <code>a &#124;> b</code> |
Expand Down Expand Up @@ -288,6 +288,12 @@ You should enable these features only if you are using an older version.

> NOTE: When a plugin is specified multiple times, only the first options are considered.

- `importAttributes`:

- `deprecatedAssertSyntax` (`boolean`, defaults to `false`)

When `true`, allow parsing import attributes using the [deprecated](https://tc39.es/proposal-import-attributes/#sec-deprecated-assert-keyword-for-import-attributes) `assert` keyword. This matches the syntax originally supported by the `importAssertions` parser plugin.

- `decorators`:

- `allowCallParenthesized` (`boolean`, defaults to `true`)
Expand Down
59 changes: 59 additions & 0 deletions docs/plugin-syntax-import-attributes.md
View file
Open in desktop
@@ -0,0 +1,59 @@
---
id: babel-plugin-syntax-import-attributes
title: "@babel/plugin-syntax-import-attributes"
sidebar_label: syntax-import-attributes
---

> #### Syntax only
>
> This plugin only enables Babel to parse this syntax. Babel does not support transforming this syntax

This plugin enables Babel to parse import attributes:

```js title="JavaScript"
import foo from "./foo.json" with { type: "json" };
```

## Installation

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

## Usage

### With a configuration file (Recommended)

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

### Via CLI

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

### Via Node API

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

## Options

### `deprecatedAssertSyntax`

`boolean`, defaults to `false`.

If enabled, support parsing import attributes using the [deprecated](https://tc39.es/proposal-import-attributes/#sec-deprecated-assert-keyword-for-import-attributes) `assert` keyword:

```js title="JavaScript"
import foo from "./foo.json" assert { type: "json" };
```

This syntax is only supported in V8-based engines, and its removal from the web is being investigated.
1 change: 1 addition & 0 deletions website/sidebars.js
View file
Open in desktop
Expand Up @@ -232,6 +232,7 @@ module.exports = {
"babel-plugin-proposal-record-and-tuple",
"babel-plugin-proposal-regexp-modifiers",
"babel-plugin-proposal-throw-expressions",
"babel-plugin-syntax-import-attributes",
],
"Web Compatibility": [
"babel-plugin-proposal-import-attributes-to-assertions",
Expand Down