Lit 3.0 Prerelease 2 and more!

Today we are publishing the second prerelease of Lit 3.0.

This prerelease includes:

• The core Lit 3.0 packages
• The first graduating class of Lit Labs: Task, Context, and React
• Our first preview of our new optimizing template compiler
• A Preact Signals integration library

There are many other packages in this prerelease. See the full list and how to try them out here.

As we announced with the first prerelease, Lit 3.0 is a breaking change that most notably removes support for IE11. As a new major version, Lit 3.0 is intended to have no new features, since new features can be added in non-breaking minor versions.

• IE11 is no longer supported.
• Lit's npm modules are now published as ES2021.
• APIs deprecated with the Lit 2.0 release have been removed.
• SSR hydration support modules are moved to the @lit-labs/ssr-client package.
• Decorator behavior has been unified between TypeScript experimental decorators and standard decorators.
• Support was removed for Babel decorators version "2018-09"

These breaking changes should have minimal impact for most users – based on testing against Google's codebase, they impact about one in a thousand elements – and allow our project to move forward more efficiently.

The one new feature that we did add to Lit 3.0 is support for the TC39 standard decorators specification to our existing decorators.

The new decorator spec has reached Stage 3 in TC39, meaning that browsers and compilers are now implementing them. This is a huge step for Lit! The arrival of standard decorators allows us to begin the process of moving to a decorator implementation that won't require a compiler to use.

It's very important to us to make the upgrade path from experimental decorators as smooth as possible. To accomplish this we made our existing decorators support the standard spec and made them work with the new accessor keyword in experimental decorator mode.

This way you can use Lit decorators with auto-accessors (using the accessor keyword) so that the same call site works with both settings:

class MyElement extends LitElement {
  @property()
  accessor myProperty = 'hello';
}

Once all decorator call sites in your project use the accessor keyword, you can build with experimentalDecorators set to true or false without a change in behavior.

But in order to make these hybrid decorators have consistent behavior in both modes we had to make a few minor breaking changes to our experimental decorators:

• We now call requestUpdate() automatically for @property and @state decorated accessors where previously that was the setter's responsibility.
• The value of an accessor is read on first render and used as the initial value for changedProperties and attribute reflection.
• @property and @state must be used on the setter for hand-written accessors.

Standard decorator mode requires TypeScript 5.2 or Babel 7.23 with the @babel/plugin-proposal-decorators plugin using decorator version "2023-05".

1. We still need to update our decorator documentation on lit.dev
2. The TypeScript and Babel emit for standard decorators is quite a bit larger than for TypeScript experimental decorators. We still recommend experimentalDecorators: true for production.

The releases today also include the first preview of our new template compiler: @lit-labs/compiler.

Our compiler is a TypeScript transform that rewrites lit-html templates into a prepared representation so that the template prep steps are skipped at runtime. This can improve first render performance, sometimes dramatically. All template behavior remains exactly the same.

We plan on offering the compiler in a number of tool plugin formats, but for now we just have a TypeScript transform. One of the easiest ways to use it is via Rollup's TypeScript plugin, which allows you to add transforms:

rollup.config.js:

import typescript from '@rollup/plugin-typescript';
import {compileLitTemplates} from '@lit-labs/compiler';

export default {
  // ...
  plugins: [
    typescript({
      transformers: {
        before: [compileLitTemplates()],
      },
    }),
    // other rollup plugins
  ],
};

Signals: they're so hot right now!

Many frameworks are adopting signals – observable holders of state and computation – for performance and DX improvements. Lit already has a very efficient rendering system, and in preliminary tests signals aren't a clear performance improvement.

For Lit developers we think signals promise to offer a convenient and relatively simple option for shared observable state, a recurring need in our community. So we are starting to explore what it would look like to integrate signals with Lit with a new @lit-labs/preact-signals package.

This package provides three ways to use Preact Signals:

1. A SignalWatcher mixin, which makes a component automatically watch all signals used during updates.
2. A watch() directive, which watches one signal and updates a binding with it.
3. A special html template tag that auto-applies the watch() directive to all bindings that use signals.

Here's an example of using the SignalWatcher mixin:

import {LitElement, html} from 'lit';
import {customElement, property} from 'lit';
import {SignalWatcher, signal} from '@lit-labs/preact-signals';

const count = signal(0);

@customElement('signal-example')
export class SignalExample extends SignalWatcher(LitElement) {

  render() {
    return html`
      <p>The count is ${count.value}</p>
      <button @click=${this._onClick}>Increment<button></button></button>
    `;
  }

  private _onClick() {
    // A change to the signal value causes the element to re-render!
    count.value = count.value + 1;
  }
}

One issue that signals present for web components is that there are many different signals implementations and no interoperability between them. This goes against the interoperability goals of web components, so for now, rather than build our own signals package or pick just one that we endorse, we plan on offering integration packages to be able to use various signal libraries with Lit.

These integrations will be relatively simple because we have two straight-forward ways of using signals:

1. Treat a component's update lifecycle as an effect, so that it's run when any signals it accesses (like in templates) changes. This integrates signals with Lit's batching async lifecycle for good performance when many signals change.
2. Use a directive to wire a signal directly to a location in DOM.

We chose Preact's signals library for our first integration because it's a relatively small, fast, and easy-to-understand implementation published to npm as standard JS modules.

We are also graduating our first set of Lit Labs packages: Context, Task, and React.

These packages have a new home in the @lit npm scope, but are otherwise exactly the same as the current labs versions. The labs packages have been updated to depend on and re-export the non-labs versions so that they share a single implementation.

To try out the prerelease, update your package.json to depend on the prerelease package versions.

The packages in the prerelease are:

• lit@3.0.0-pre.1
• lit-element@4.0.0-pre.1
• lit-html@3.0.0-pre.1
• @lit/reactive-element@2.0.0-pre.1
• @lit/context@1.0.0-pre.0
• @lit/react@1.0.0-pre.0
• @lit/task@1.0.0-pre.0
• @lit-labs/compiler@1.0.0-pre.0
• @lit-labs/preact-signals@1.0.0-pre.0

You should also update dependencies on our other packages so that they pick up the Lit prerelease as well.

Remember that Lit 2.x and Lit 3.0 are interoperable, so even if some of your dependencies are using Lit 2.x you can try the Lit 3.0 prerelease on your components!

You can view the Lit 3.0 docs on lit.dev at https://lit.dev/docs/v3/ .

We are still updating some of the docs, our main task until the final release of Lit 3.0.

We hope you enjoy Lit 3.0! If you have questions or feedback, please let us know in GitHub issues or on our Lit and Friends Discord.

Thanks! - The Lit Team