You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/lit-dev-content/site/docs/components/decorators.md
+26-32Lines changed: 26 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -73,25 +73,34 @@ In the future when decorators become a native web platform feature, this may no
73
73
74
74
To use decorators with [TypeScript](https://www.typescriptlang.org/docs/handbook/decorators.html), enable the `experimentalDecorators` compiler option.
75
75
76
+
You should also ensure that the `useDefineForClassFields` setting is `false`. Note, this should only be required when the `target` is set to `esnext` or greater, but it's recommended to explicitly ensure this setting is `false`.
77
+
76
78
```json
77
79
"experimentalDecorators": true,
80
+
"useDefineForClassFields": false,
78
81
```
79
82
80
83
Enabling `emitDecoratorMetadata` is not required and not recommended.
81
84
82
85
### Using decorators with Babel { #decorators-babel }
83
86
84
-
If you're compiling JavaScript with [Babel](https://babeljs.io/docs/en/), you can enable decorators by adding the following plugins:
87
+
If you're compiling JavaScript with [Babel](https://babeljs.io/docs/en/), you can enable decorators by adding the following plugins and settings:
@@ -101,42 +110,19 @@ Currently the older `legacy` mode of Babel decorators is not supported, but this
101
110
102
111
</div>
103
112
104
-
### Avoiding issues with class fields
105
-
106
-
Class fields are a [stage 3 proposal](https://github.com/tc39/proposal-decorators) for addition to the ECMAScript standard. They currently have a problematic interaction with the decorators proposal in some circumstances.
107
-
108
-
There are generally no issues when using TypeScript. However, it's important to ensure that the `useDefineForClassFields` setting in your `tsconfig` is set to false. This is currently the default setting.
109
-
110
-
When using Babel, class fields should only be used for properties that are defined with a decorator.
111
-
112
-
<divclass="alert alert-info">
113
-
Using the `static properties` syntax along with class fields is not supported.
114
-
</div>
115
-
116
-
The following is ok:
117
-
118
-
```js
119
-
@property()
120
-
foo ='bar';
121
-
```
122
-
123
-
but this is **not supported**:
124
-
125
-
```js
126
-
static properties = { foo: {} };
127
-
foo ='bar';
128
-
```
129
-
130
-
### Using TypeScript with Babel
113
+
### Using decorators with TypeScript and Babel
131
114
132
115
When using TypeScript with Babel, it's important to order the TypeScript transform before the decorators transform in your Babel config as follows:
### Avoiding issues with class fields and decorators {#avoiding-issues-with-class-fields}
144
+
145
+
[Class fields](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields) have a problematic interaction with declaring reactive properties. See [Avoiding issues with class fields when declaring properties](/docs/components/properties/#avoiding-issues-with-class-fields) for more information.
146
+
147
+
The current decorators [stage 3 proposal](https://github.com/tc39/proposal-decorators) does not directly address this issue, but it should be solved as the proposal evolves and matures.
148
+
149
+
When using decorators, transpiler settings for Babel and TypeScript must be configured correctly as shown in the sections above for [TypeScript](#decorators-typescript) and [Babel](#decorators-babel).
Copy file name to clipboardExpand all lines: packages/lit-dev-content/site/docs/components/properties.md
+26-3Lines changed: 26 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -115,11 +115,34 @@ class MyElement extends LitElement {
115
115
116
116
An empty option object is equivalent to specifying the default value for all options.
117
117
118
-
<divclass="alert alert-info">
118
+
### Avoiding issues with class fields when declaring properties {#avoiding-issues-with-class-fields}
119
119
120
-
**If you're using the static properties field, initialize properties in the constructor**. Class field initializers won't work in this case.
120
+
[Class fields](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields) have a problematic interaction with reactive properties. Class fields are defined on the element instance. Reactive properties are defined as accessors on the element prototype. According to the rules of JavaScript, an instance property takes precedence over and effectively hides a prototype property. This means that reactive property accessors do not function when class fields are used. When a property is set, the element does not update.
121
121
122
-
</div>
122
+
In **JavaScript** you **must not use class fields** when declaring reactive properties. Instead, properties must be initialized in the element constructor:
123
+
124
+
```js
125
+
constructor() {
126
+
super();
127
+
this.data= {};
128
+
}
129
+
```
130
+
131
+
For **TypeScript**, you **may use class fields** for declaring reactive properties as long as the `useDefineForClassFields` setting in your `tsconfig` is set to `false`. Note, this is not required for some configurations of TypeScript, but it's recommended to explicitly set it to `false`.
132
+
133
+
When compiling JavaScript with **Babel**, you **may use class fields** for declaring reactive properties as long as you set `setPublicClassFields` to `true` in the `assumptions` config of your `babelrc`. Note, for older versions of Babel, you also need to include the plugin `@babel/plugin-proposal-class-properties`:
134
+
135
+
```js
136
+
assumptions = {
137
+
"setPublicClassFields":true
138
+
};
139
+
140
+
plugins = [
141
+
["@babel/plugin-proposal-class-properties"],
142
+
];
143
+
```
144
+
145
+
For information about using class fields with **decorators**, see [Avoiding issues with class fields and decorators](/docs/components/decorators/#avoiding-issues-with-class-fields).
Copy file name to clipboardExpand all lines: packages/lit-dev-content/site/docs/tools/publishing.md
+11-3Lines changed: 11 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,10 +46,13 @@ The following JSON sample is a partial `tsconfig.json` that uses recommended opt
46
46
"lib": ["es2019", "dom"],
47
47
"declaration": true,
48
48
"declarationMap": true,
49
-
"experimentalDecorators": true
49
+
"experimentalDecorators": true,
50
+
"useDefineForClassFields": false
50
51
}
51
52
```
52
53
54
+
Note, setting `useDefineForClassFields` to `false` should only be required when the `target` is set to `esnext` or greater, but it's recommended to explicitly ensure this setting is `false`.
55
+
53
56
When compiling from TypeScript, you should include declaration files
54
57
(generated based on `declaration: true` above) for your component's types in the
55
58
`types` field of `package.json`, and ensure the `.d.ts` and `.d.ts.map` files
You can run Babel via a bundler plugin such as [@rollup/plugin-babel](https://www.npmjs.com/package/@rollup/plugin-babel), or from the command line. See the [Babel documentation](https://babeljs.io/docs/en/) for more information.
0 commit comments