Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/salesforce/lwc-codemod

Codemods for Lightning Web Components
https://github.com/salesforce/lwc-codemod

Last synced: 10 days ago
JSON representation

Codemods for Lightning Web Components

Lists

README 

        
# lwc-codemod



Codemods for [LWC](https://lwc.dev/). In other words: scripts to transform LWC component code.



This tool currently can:



- convert components from shadow DOM to [light DOM](https://lwc.dev/guide/light_dom#light-dom-(developer-preview))

- convert components from synthetic shadow DOM to [native shadow DOM](https://rfcs.lwc.dev/rfcs/lwc/0115-mixed-shadow-mode)

- clean up HTML syntax errors



## Installation



```sh

npm i -g lwc-codemod

```



Or, to avoid installing globally, use `npx lwc-codemod`.



## Basic usage



```sh

lwc-codemod  

```



When you pass in a ``, the script will crawl all components inside of that path:



```sh

lwc-codemod  /path/to/my/components/

```



## Transforms



Available transforms:



- [Shadow DOM to Light DOM](#shadow-dom-to-light-dom) (`shadow-to-light`)

- [Synthetic Shadow DOM to Native Shadow DOM](#synthetic-shadow-dom-to-native-shadow-dom) (`synthetic-to-native`)

- [HTML Template Cleanup](#html-template-cleanup) (`html-template-cleanup`)



### Shadow DOM to Light DOM



#### Usage



```sh

lwc-codemod shadow-to-light 

```



#### Summary



Converts components from shadow DOM to light DOM.



#### JS



- Adds `static renderMode = 'light'`

- `this.template` -> `this` (and destructuring equivalents)



#### HTML



- Adds `lwc:render-mode="light"`

- Removes `lwc:dom="manual"`



#### CSS



- Moves `foo.css` to `foo.scoped.css`



#### `lwc:dom="manual"`



For this case, the styles still need to be scoped to the `lwc:dom="manual"` tree. So the codemod creates an additional global CSS file containing selectors to replace e.g. `div` with `.auto-generated div`, where `auto-generated` is a class applied to `lwc:dom="manual"` nodes.



#### Slots



For slots, a wrapper `
` is created around the ``so that this `
` can be targeted in the CSS and have events attached to it, e.g. `onscroll` events.



`onslotchange` is currently not implemented. As an alternative, you can use [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) or explicit signalling between components to notify of changes. 



### Synthetic Shadow DOM to Native Shadow DOM



#### Usage



```sh

lwc-codemod synthetic-to-native 

```



#### Summary



Converts components from synthetic shadow to native shadow.



The only transformation it currently applies is to add the `static shadowSupportMode` property. Any other discrepancies between native shadow and synthetic shadow will have to be handled manually.



### HTML Template Cleanup



#### Usage



```sh

lwc-codemod html-template-cleanup 

```



#### Summary



Fixes several HTML warnings/errors generated by the `@lwc/template-compiler`



##### Multiple `if:true`/`if:false` Directives on the Same Element



Removes excessive `if:true` and `if:false` attributes that appear on the same element. 



Only the first `if:true`/`if:false` is processed in LWC. This mod will remove all other instances, since they would have no effect.



For example:



```html



    



```



Will become



```html



    



```



##### Invalid Template Attributes



Removes invalid attributes from both root and non-root `templates`.



These attributes are ignored by LWC during parsing, and are thus safe to remove.



For example:



```html



    hello world!



```



Will become:



```html



    hello world!



```



See the official [documentation](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.reference_directives) for valid `template` attributes.



Note that for non-root `template` elements, if there aren't any valid directives, the content inside the `template` will not be rendered.



As a corrective measure, this mod will therefore remove any `template` elements without valid directives.



##### HTML parsing errors



Fixes errors generated during LWC HTML parsing.



The following transforms are available for each errors:



###### `eof-in-element-that-can-contain-only-text`



This is an unexpected end of file in an element that can only contain text. 



```html



    eof-in-element-that-can-contain-only-text

asdf

```



###### `end-tag-without-matching-open-element`



This is a closing `template` tag without a matching opening tag.



```html



    end-tag-without-matching-open-element



```



###### `closing-of-element-with-open-child-elements`



This is an unexpected closing tag with open child elements.



```html



    

        closing-of-element-with-open-child-elements



```



## Contributing



Install dependencies:



```sh

yarn

```



Run tests:



```sh

yarn test

```



Run the linter:



```sh

yarn lint

```