lit
@lit/ts-transformers
TypeScript transformers for the Lit decorators.
Install
npm i @lit/ts-transformersTransformers
idiomaticDecoratorsTransformer
import {idiomaticDecoratorsTransformer} from '@lit/ts-transformers';Replaces all of the official Lit class and property decorators with idiomatic vanilla JavaScript.
Must run as a before transformer.
Example input
import {LitElement, html} from 'lit';
import {customElement, property} from 'lit/decorators.js';
@customElement('simple-greeting')
class SimpleGreeting extends LitElement {
@property()
name = 'World';
render() {
return html`<p>Hello ${this.name}!</p>`;
}
}Example output
import {LitElement, html} from 'lit';
class SimpleGreeting extends LitElement {
static properties = {
str: {},
};
constructor() {
super();
this.name = 'World';
}
render() {
return html`Hello ${this.name}!`;
}
}
customElements.define('simple-greeting', SimpleGreeting);Supported decorators
| Decorator | Transformer behavior |
|---|---|
@customElement |
Adds a customElements.define call |
@property |
Adds an entry to static properties, and moves initializers to the constructor |
@state |
Same as @property with {state: true} |
@query |
Defines a getter that calls querySelector |
@querySelectorAll |
Defines a getter that calls querySelectorAll |
@queryAsync |
Defines an async getter that awaits updateComplete and then calls querySelector |
@queryAssignedElements |
Defines a getter that calls querySelector('slot[name=foo]').assignedElements |
@queryAssignedNodes |
Defines a getter that calls querySelector('slot[name=foo]').assignedNodes |
@localized |
Adds an updateWhenLocaleChanges call to the constructor |
preserveBlankLinesTransformer
import {
preserveBlankLinesTransformer,
BLANK_LINE_PLACEHOLDER_COMMENT,
BLANK_LINE_PLACEHOLDER_COMMENT_REGEXP,
} from '@lit/ts-transformers';A readability transformer that replaces blank lines in the original source with a special comment, because TypeScript does not otherwise preserve blank lines when it emits (see TypeScript#843).
The comment is always exactly:
//__BLANK_LINE_PLACEHOLDER_G1JVXUEBNCL6YN5NFE13MD1PT3H9OIHB__Must run as a before transformer, and should usually placed in front of
all other transformers.
constructorCleanupTransformer
import {constructorCleanupTransformer} from '@lit/ts-transformers';A readability transformer that does the following:
Moves constructors back to their original source position, or below the last
staticfield if they are fully synthetic. By default, constructors will move to the top of a class whenever they are modified by TypeScript.Simplifies
super(...)calls tosuper()in class constructors, unless the class has any super-classes with constructors that takes parameters according to the type-checker.
Must run as an after transformer.
Usage
There are a number of ways to compile a TypeScript program with transformers.
TypeScript compiler API
If you are using the TypeScript compiler
API
directly, pass the transformer to the customTransformers parameter of emit.
Example:
import ts from 'typescript';
import {
idiomaticDecoratorsTransformer,
preserveBlankLinesTransformer,
constructorCleanupTransformer,
} from '@lit/ts-transformers';
// Note this is not a complete example. For more information see
// https://github.com/microsoft/TypeScript-wiki/blob/master/Using-the-Compiler-API.md
const program = ts.createProgram(...);
const result = program.emit(undefined, undefined, undefined, undefined, {
before: [
// Optionally preserve blank lines for better readability.
preserveBlankLinesTransformer(),
// Transform Lit decorators to idiomatic vanilla JavaScript.
idiomaticLitDecoratorTransformer(program),
],
after: [
// Optional readability improvements for constructors.
constructorCleanupTransformer(program),
],
});ttypescript / ts-patch
ttypescript and
ts-patch are two similar tools that
augment the TypeScript compiler, adding the ability to declare transforms in
your tsconfig.json.
Example:
{
"compilerOptions": {
"plugins": [
{
"transform": "@lit/ts-transformers",
"import": "preserveBlankLinesTransformer"
},
{
"transform": "@lit/ts-transformers",
"import": "idiomaticDecoratorsTransformer"
},
{
"transform": "@lit/ts-transformers",
"import": "constructorCleanupTransformer",
"after": true
}
]
}
}If preserveBlankLinesTransformer is used, one way to remove blank line
placeholder comments is with sed:
sed -i $'s/\s*\/\/__BLANK_LINE_PLACEHOLDER_G1JVXUEBNCL6YN5NFE13MD1PT3H9OIHB__/\\\n/g' lib/*.js lib/**/*.js@rollup/plugin-typescript
@rollup/plugin-typescript is a Rollup plugin for compiling TypeScript that includes support for transformers.
Example:
import typescript from '@rollup/plugin-typescript';
import resolve from '@rollup/plugin-node-resolve';
import replace from '@rollup/plugin-replace';
import {
idiomaticDecoratorsTransformer,
preserveBlankLinesTransformer,
constructorCleanupTransformer,
BLANK_LINE_PLACEHOLDER_COMMENT,
} from '@lit/ts-transformers';
export default {
input: './src/my-element.ts',
plugins: [
typescript({
transformers: {
before: [
// Optionally preserve blank lines for better readability.
{factory: preserveBlankLinesTransformer},
// Transform Lit decorators to idiomatic vanilla JavaScript.
{type: 'program', factory: idiomaticDecoratorsTransformer},
],
after: [
// Optional readability improvements for constructors.
{type: 'program', factory: constructorCleanupTransformer},
],
},
}),
// Only for when using preserveBlankLinesTransformer.
replace({
values: {
[`//${BLANK_LINE_PLACEHOLDER_COMMENT}`]: '',
},
delimiters: ['', ''],
}),
resolve(),
],
output: {
file: 'dist/my-element.js',
format: 'esm',
},
};