Beef up docs around using class fields #516
Conversation
|
A live preview of this PR will be available at the URL(s) below. https://pr516-f3307b0---lit-dev-5ftespv5na-uc.a.run.app/ |
| [Class fields](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields) have a problematic interaction with declaring 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. | ||
|
|
||
| </div> | ||
| **You can use class fields** with reactive properties when transpiling code with Babel or TypeScript and the proper settings are enabled. Both Babel and TypeScript support transpiling class fields into properties set in the constructor rather than defined on the instance. |
There was a problem hiding this comment.
Suggest removing this paragraph, kinda seems like it's mostly redundant with the next two paragraphs, which are more focused.
|
|
||
| To use decorators with [TypeScript](https://www.typescriptlang.org/docs/handbook/decorators.html), enable the `experimentalDecorators` compiler option. | ||
|
|
||
| You should also ensure that the `useDefineForClassFields` setting is `false`. Note, this should only be required when the `target` is set to `es2020` or greater, but it's recommended to explicitly ensure this setting is `false`. |
There was a problem hiding this comment.
I believe it's only for esnext, not es2020 (microsoft/TypeScript#34787)
Co-authored-by: Alexander Marks <[email protected]>
Co-authored-by: Alexander Marks <[email protected]>
Co-authored-by: Alexander Marks <[email protected]>
Co-authored-by: Alexander Marks <[email protected]>
| ### Using decorators with Babel { #decorators-babel } | ||
|
|
||
| If you're compiling JavaScript with [Babel](https://babeljs.io/docs/en/), you can enable decorators by adding the following plugins: | ||
| If you're compiling JavaScript with [Babel](https://babeljs.io/docs/en/), you can enable decorators by adding the following plugins and assumptions: |
There was a problem hiding this comment.
Using "assumptions" here is super jargony. You'd have to be pretty well-versed in Babel to know that there are config options called "Compiler assumptions," and the average user is likely to infer the generic meaning for assumptions here.
Suggest either just go with "plugins" and assume (heh) that the configuration steps that follow are part of adding the plugins, or say, "plugins and settings"
There was a problem hiding this comment.
Changed to "plugins and settings"
Co-authored-by: Arthur Evans <[email protected]>
3 participants
Fixes #462