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

Add docs for the new decorators transform #2614

Merged
merged 2 commits into from
Feb 2, 2022
Merged

Add docs for the new decorators transform #2614

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
133ce5a
Update decorators docs
nicolo-ribaudo Jan 31, 2022
0f39afa
Review
nicolo-ribaudo Feb 1, 2022
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
44 changes: 23 additions & 21 deletions docs/plugin-proposal-decorators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,17 +80,31 @@ require("@babel/core").transformSync("code", {

## Options

### `decoratorsBeforeExport`

`boolean`

<details>
<summary>History</summary>
| Version | Changes |
| --- | --- |
| `v7.2.0` | `decoratorsBeforeExport` must be specified. Before that it defaults to `false` |
JLHwung marked this conversation as resolved.
Show resolved Hide resolved
| `v7.17.0` | Added the `version` option with support for `"2021-12"`, `"2018-09"` and `"legacy"` |
</details>

### `version`

`"2021-12"`, `"2018-09"` or `"legacy"`. Defaults to `"2018-09"`.

Selects the decorators proposal to use:
- `"2021-12"` is the proposal version as it was presented to TC39 in Dec 2021. You can read more about it at [`tc39/proposal-decorators@d6c056fa06`](https://github.com/tc39/
- `"2018-09"` is the proposal version that was initially promoted to Stage 2 presented to TC39 in Sept 2018. You can read more about it at [`tc39/proposal-decorators@7fa580b40f`](https://github.com/tc39/proposal-decorators/tree/7fa580b40f2c19c561511ea2c978e307ae689a1b).proposal-decorators/tree/d6c056fa061646178c34f361bad33d583316dc85).
- `legacy` is the original Stage 1 proposal, defined at [`wycats/javascript-decorators@e1bf8d41bf`](https://github.com/wycats/javascript-decorators/blob/e1bf8d41bfa2591d949dd3bbf013514c8904b913/README.md).

### `decoratorsBeforeExport`

This option:
- is disallowed when using `version: "legacy"`;
- is required when using `version: "2018-09"`;
- is optional and defaults to `false` when using `version: "2021-12"`.

`boolean`

```js
// decoratorsBeforeExport: false
export @decorator class Bar {}
Expand All @@ -106,6 +120,8 @@ For more information, check out: [tc39/proposal-decorators#69](https://github.co

### `legacy`

> **⚠️ DEPRECATED**: Use `version: "legacy"` instead. This option is a legacy alias.

`boolean`, defaults to `false`.

Use the legacy (stage 1) decorators syntax and behavior.
Expand All @@ -114,15 +130,13 @@ Use the legacy (stage 1) decorators syntax and behavior.

If you are including your plugins manually and using `@babel/plugin-proposal-class-properties`, make sure that `@babel/plugin-proposal-decorators` comes _before_ `@babel/plugin-proposal-class-properties`.

When using the `legacy: true` mode, the [`setPublicClassFields` assumption](assumptions.md#setpublicclassfields) must be enabled to support the `@babel/plugin-proposal-decorators`.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has not been necessary for years - babel/babel#14133


Wrong:

```json
{
"plugins": [
"@babel/plugin-proposal-class-properties",
"@babel/plugin-proposal-decorators"
["@babel/plugin-proposal-decorators", { "legacy": true }]
]
}
```
Expand All @@ -131,21 +145,9 @@ Right:

```json
{
"plugins": [
"@babel/plugin-proposal-decorators",
"@babel/plugin-proposal-class-properties"
]
}
```

```json
{
"assumptions": {
"setPublicClassFields": true
},
"plugins": [
["@babel/plugin-proposal-decorators", { "legacy": true }],
["@babel/plugin-proposal-class-properties"]
"@babel/plugin-proposal-class-properties"
]
}
```
Expand Down
23 changes: 1 addition & 22 deletions docs/plugin-syntax-decorators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,27 +40,6 @@ require("@babel/core").transformSync("code", {

## Options

### `legacy`

`boolean`, defaults to `false`.

Use the legacy (stage 1) decorators syntax.

### `decoratorsBeforeExport`

`boolean`

```js
// decoratorsBeforeExport: true
@decorator
export class Foo {}

// decoratorsBeforeExport: false
export @decorator class Bar {}
```

This option was added to help tc39 collect feedback from the community by allowing experimentation with both possible syntaxes.

For more information, check out: [tc39/proposal-decorators#69](https://github.com/tc39/proposal-decorators/issues/69)
This plugin accepts the same options as [`@babel/plugin-proposal-decorators`](plugin-proposal-decorators.md).

> You can read more about configuring plugin options [here](https://babeljs.io/docs/en/plugins#plugin-options)