Acknowledgement

• I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.

Comment

This GitHub issue contains feedback on the Standard Decorators emit size from the Lit team.

Summary

It is difficult to recommend usage of Standard Decorators with the current JavaScript emit size.

Background

Lit supplies a set of decorators that reduce the amount of boilerplate code you need to write when defining a component.

For example, the material web button component implementation, uses Lit’s @property decorator to annotate a field that triggers a reactive update.

Measurement

The Material Web repository was used to test the emit size when using Standard Decorators. Note, this was done quite naively to get ballpark figures.

The following table has emitted JavaScript target as “es2022”, and no emitted JavaScript minification:

Results when minifying the emitted JavaScript with Terser:

Emit size of the Material Button implementation (without styles)

The material-web repository contains a lot of styles which are also emitted as JavaScript and incorporated in the numbers above. As a smaller benchmark, here is a single file which contains a single component.

Source code: https://github.com/material-components/material-web/blob/v1.0.0-pre.16/button/internal/button.ts

Contents of button.js with experimental decorators here: https://pastebin.com/TiiYSDye
Contents of button.js with standard decorators here: https://pastebin.com/2nfpYApy

Lit team's perspective

At the library level we can support both experimental and standard decorator APIs in the same decorator implementations. We've got a branch that works great with the type checker and at runtime. Philosophically we're aligned with standard decorators, and in the long run they're the obvious choice. But, the size increase when downleveling standard decorators makes them a performance footgun for users, one that will need to be a prominent part of the documentation of our decorators.

One solution we're evaluating is to add a decorators pass to our optimizing TypeScript compiler plugin. A library-specific optimization pass can take advantage of the specific semantics of known decorators to produce output at least as good as the experimental decorators pass. One downside of this approach however is that it can only optimize known decorators, and many users will use decorators from other libraries, and author their own. And, since this is a new compiler from us, no one uses it yet, and uptake may be slow and incomplete.