Skip to content

Commit

Permalink
doc: configure ejected create-react-app to support decorators (micros…
Browse files Browse the repository at this point in the history
…oft#5682)

* add documentation to support decorators in cra

* Change files

* Apply suggestions from code review

use correct grammer

Co-authored-by: Rob Eisenberg <EisenbergEffect@users.noreply.github.com>

Co-authored-by: Wendy <wendy@Wendys-MacBook-Pro-Microsoft.local>
Co-authored-by: Rob Eisenberg <EisenbergEffect@users.noreply.github.com>
  • Loading branch information
3 people authored Mar 2, 2022
1 parent 182c888 commit 26ce299
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 3 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"type": "none",
"comment": "add documentation to support decorators in cra",
"packageName": "@microsoft/fast-foundation",
"email": "email not defined",
"dependentChangeType": "none"
}
44 changes: 41 additions & 3 deletions packages/web-components/fast-foundation/docs/integrations/react.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,9 +170,11 @@ provideFASTDesignSystem()
The `wrap` helper can also wrap any FAST Web Component defined using the `@customElement` decorator or by manually calling `FASTElement.define`. To do so, pass the custom element class to the wrapper.

```ts
import { FASTElement, customElement, html } from '@microsoft/fast-element';

@customElement({
name: 'my-component',
template:...,
template: html`...`,
styles:...
})
class _MyComponent extends FASTElement {
Expand All @@ -181,7 +183,9 @@ class _MyComponent extends FASTElement {

export const MyComponent = provideReactWrapper(React).wrap(_MyComponent);
```

:::note
When using decorators in a create-react-app setup, you will most likely get this error `Support for the experimental syntax 'decorators-legacy' isn't currently enabled`. See the "Additional Notes" below for options to add support for decorators.
:::
### Wrapping VanillaJS Web Components

If you have a component from a 3rd party library, not written with FAST, or a VanillaJS Web Component, you can wrap that as well. In this scenario you will have to provide some additional information, such as the element name and the list of properties that should be handled by the wrapper rather than React. Components created with libraries like `Lit` require the element name to be configured but not the properties, while some other libraries or hand-written components may also require the property list. This depends on how the component was defined. Below is an example of configuring both the name and the property list.
Expand Down Expand Up @@ -234,7 +238,41 @@ FAST makes use of decorators to define components. At this time, `create-react-a
- Use an intermediary like [react-app-rewired](https://www.npmjs.com/package/react-app-rewired)

You can read more about decorator configuration issues [here.](https://github.com/microsoft/fast/issues/4503)

### Configure ejected create-react-app

Eject create-react-app:
```shell
npm run eject
```

Install babel plugins:
```shell
npm i --save-dev @babel/plugin-proposal-decorators @babel/preset-env
```
#### Configure babel-loader options

Go to the `webpack.config.js` file under the `config` folder and find where `babel-loader` is (around line 407).

Add `@babel/preset-env` to presets. This allows you to use the latest JavaScript features.
Targeting specific browser versions prevents Babel from transpiling too much to support old JavaScript versions, increasing file size.

```js
presets: [
["@babel/preset-env", {
"targets": {
"browsers": ["last 2 versions", "safari >= 7"]
}
}],
...
```
Add `@babel/plugin-proposal-decorators` to support decorators.

```js
plugins: [
["@babel/plugin-proposal-decorators", { "legacy": true }],
...
```

### Working without the fast-react-wrapper

The `@microsoft/fast-react-wrapper` library described above addresses all the challenges involved in using Web Components from React. We strongly recommend using this library for integration. However, if you cannot use this library or want to explore other options, below you'll find information on alternative approaches.
Expand Down

0 comments on commit 26ce299

Please sign in to comment.