Skip to content

Commit

Permalink
Ad docs for import attributes (#2780)
Browse files Browse the repository at this point in the history 
* Ad docs for import attributes

* Add `deprecatedAssertSyntax` default value

* Add to sidebar
  • Loading branch information
@nicolo-ribaudo
nicolo-ribaudo committed May 26, 2023
1 parent 8cb0546 commit ac754a6
Show file tree
Hide file tree
Showing 4 changed files with 88 additions and 20 deletions.
34 changes: 18 additions & 16 deletions docs/generator.md
View file
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
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
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
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

0 comments on commit ac754a6

Please sign in to comment.