/lwc-codemod

Codemods for Lightning Web Components

Primary LanguageJavaScriptBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

lwc-codemod

Codemods for LWC. In other words: scripts to transform LWC component code.

This tool currently can:

  • convert components from shadow DOM to light DOM
  • convert components from synthetic shadow DOM to native shadow DOM
  • clean up HTML syntax errors

Installation

npm i -g lwc-codemod

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

Basic usage

lwc-codemod <transform> <path>

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

lwc-codemod <transform> /path/to/my/components/

Transforms

Available transforms:

Shadow DOM to Light DOM

Usage

lwc-codemod shadow-to-light <directory>

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 <div> is created around the <slot>so that this <div> 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 or explicit signalling between components to notify of changes.

Synthetic Shadow DOM to Native Shadow DOM

Usage

lwc-codemod synthetic-to-native <path>

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

lwc-codemod html-template-cleanup <path>

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:

<template>
    <div if:true={visible} if:false={visible}></div>
</template>

Will become

<template>
    <div if:true={visible}></div>
</template>
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:

<template class="slds-style">
    <span>hello world!</span>
</template>

Will become:

<template>
    <span>hello world!</span>
</template>

See the official documentation 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.

<template>
    <span>eof-in-element-that-can-contain-only-text</span>
<textarea>asdf
end-tag-without-matching-open-element

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

<template>
    <span>end-tag-without-matching-open-element</span>
</template>
</template>
closing-of-element-with-open-child-elements

This is an unexpected closing tag with open child elements.

<template>
    <section>
        <span>closing-of-element-with-open-child-elements</span>
</template>

Contributing

Install dependencies:

yarn

Run tests:

yarn test

Run the linter:

yarn lint