npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@lit/ts-transformers

v2.0.1

Published

TypeScript transformers for Lit

Downloads

271

Readme

@lit/ts-transformers

Published on NPM Test status

TypeScript transformers for the Lit decorators.

Install

npm i @lit/ts-transformers

Transformers

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:

  1. Moves constructors back to their original source position, or below the last static field if they are fully synthetic. By default, constructors will move to the top of a class whenever they are modified by TypeScript.

  2. Simplifies super(...) calls to super() 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',
  },
};