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 1 commit
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:
- `legacy` is the original Stage 1 one
Copy link
Contributor

Choose a reason for hiding this comment

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

For reference here is the stage 1 spec: https://github.com/wycats/javascript-decorators/blob/e1bf8d41bfa2591d949dd3bbf013514c8904b913/README.md

- `"2018-09"` is the proposal version that was initially promoted to Stage 2 presented to TO39 in Sept 2018. You can read more about it at [`tc39/proposal-decorators@7fa580b40f`](https://github.com/tc39/proposal-decorators/tree/7fa580b40f2c19c561511ea2c978e307ae689a1b)
existentialism marked this conversation as resolved.
Show resolved Hide resolved
- `"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/proposal-decorators/tree/d6c056fa061646178c34f361bad33d583316dc85).
Copy link
Contributor

Choose a reason for hiding this comment

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

nit: I would prefer we sort the version candidates from latest to oldest.


### `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: 23 additions & 0 deletions docs/plugin-syntax-decorators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,26 @@ require("@babel/core").transformSync("code", {

## Options

<details>
Copy link
Contributor

@JLHwung JLHwung Feb 1, 2022 •
edited

Choose a reason for hiding this comment

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

Since the usage of syntax-decorators is rare, we can just leave a "see also" redirect link to the transform plugin and remove the whole "Options" section, so we don't have to maintain them at all.

<summary>History</summary>
| Version | Changes |
| --- | --- |
| `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:
- `legacy` is the original Stage 1 one
- `"2018-09"` is the proposal version that was initially promoted to Stage 2 presented to TO39 in Sept 2018. You can read more about it at [`tc39/proposal-decorators@7fa580b40f`](https://github.com/tc39/proposal-decorators/tree/7fa580b40f2c19c561511ea2c978e307ae689a1b)
- `"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/proposal-decorators/tree/d6c056fa061646178c34f361bad33d583316dc85).

### `legacy`

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

`boolean`, defaults to `false`.

Use the legacy (stage 1) decorators syntax.
Expand All @@ -50,6 +68,11 @@ Use the legacy (stage 1) decorators syntax.

`boolean`

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"`.

```js
// decoratorsBeforeExport: true
@decorator
Expand Down