The Lit team is excited to announce the first pre-releases of Lit 3.0!
Lit 3.0 is our first major version since introducing the unified Lit project and Lit 2.0 two years ago. We really value stability and backwards compatibility for our community, so we've focused on adding new features with minor versions of the core libraries and new labs packages, and not making any breaking changes.
But the time is right for just a few breaking changes that will improve development velocity and testing stability on the core Lit project.
Changes
Lit 3.0 adds no new features, because new features are generally not breaking changes and can be added in minor versions, according to semver. The Lit 3.0 release is an opportunity to make a few breaking changes that trim out some technical debt to unlock new features we have scheduled for our 3.x release series.
The Lit 3.0 changes are mostly in browser support, removing deprecated APIs, and how packages are published. If you run Lit 2.x with no deprecation warnings, this should be a seamless upgrade!
Here are the biggest things Lit 3.0 changes:
IE11 is no longer supported.
Lit's npm modules are now published as ES2021.
APIs deprecated during the Lit 1.x release timeframe have been removed.
SSR hydration support modules were moved to the @lit-labs/ssr-client package.
We would love your help testing the new versions, to ensure a smooth upgrade process with the final releases. We're especially interested in making sure the new language version works with your toolchains. We expect some users may need to upgrade their tooling to the latest versions.
You can try the pre-releases out by updating your package.json file to include the following:
"lit": "^3.0.0-pre.0"
"lit-html": "^3.0.0-pre.0"
"lit-element": "^4.0.0-pre.0"
"@lit/reactive-element": "^2.0.0-pre.0"
You can also use the pre npm tag, like npm i lit@pre.
All other packages, like labs packages, have pre-release versions too that depend on the pre-release core libraries. If you depend on those you'll have to update them too. If you're more daring you can use npm overrides to select the pre-releases even for dependencies. This should work for most dependencies.
Even if dependencies are using Lit 2.x, the good news is that Lit 2.x and Lit 3.x are interoperable, because:
The inherent interoperability web components: components built with different libraries work together, including those build with different versions of Lit.
We made interop of core features like templates and directives a priority for Lit 2. You can share templates, directives, decorators, etc., across Lit versions.
Docs
We are preparing new docs for 3.0 on lit.dev. Even though these will be mostly the same as 2.x, we are clarifying the browser and toolchain support, and want to make it easy to select the right docs set for the version you're using to enable future changes specific to to 3.x. At the 3.0 launch, we’ll archive the 2.x docs (but they will remain available in the doc version dropdown, as will 1.x). During the 3.0 pre-release phase, 2.x will remain the default, and you can select v3 from the dropdown next to the Documentation tab.
