Updating to Lit 2

Updating to Lit 2

With this pre release we update all of our packages to support Lit - Simple. Fast. Web Components..

1. Update your code to Lit 2.0

   Lit 2.0 is designed to work with most code written for LitElement 2.x and lit-html 1.x. There are a small number of changes required to migrate your code to Lit 2.0. The high-level changes required include:

   1. Updating npm packages and import paths.
   2. Loading polyfill-support script when loading the web components polyfills.
   3. Updating any custom directive implementations to use new class-based API and associated helpers.
   4. Updating code to renamed APIs.
   5. Adapting to minor breaking changes, mostly in uncommon cases.

   If you have existing lit-element components be sure to follow the rest of the official upgrade guide.

2. Update to the @open-wc pre release tooling as needed

It will be our first breaking change to our testing and testing helpers package for ~2 years. We encourage you to test it out.

You can expect the following in this pre release:

@open-wc/testing@next & @open-wc/testing-helpers@next

You can get the prerelease via

npm i -D @open-wc/testing@next @open-wc/testing-helpers@next

• Upgrade to support latest lit package.

• The exports html and unsafeStatic are now deprecated we recommend to import them directly from lit/static-html.js;

• The scopedElements is now following the Scoped Custom Element Registries and automatically loads a polyfill @webcomponents/scoped-custom-element-registry

• We now enforce our entrypoints via an export map

• The side effect free import got renamed to pure

  // old
  import { fixture } from '@open-wc/testing-helpers/index-no-side-effects.js';
  // new
  import { fixture } from '@open-wc/testing-helpers/pure';
  

• (only testing): We now use an es module version of chai from @esm-bundle/chai.

Migration:

• Any import not being as follows need to be adjust to one of those

  import { fixture } from '@open-wc/testing';
  import { fixture } from '@open-wc/testing/pure';
  import { fixture } from '@open-wc/testing-helpers';
  import { fixture } from '@open-wc/testing-helpers/pure';
  

• Directives in tests need to use the updated lit directive api (migration guide)

• We are now using an es module version of chai - therefore global chai plugins that register via a side effect will no longer work. You will need to create or find an es module version of your plugins and load it as follows

  import chai from '@esm-bundle/chai';
  import esmVersionOfPlugin from 'esm-version-of-plugin.js';
  
  chai.use(esmVersionOfPlugin);
  

@open-wc/scoped-elements@next

You can get the prerelease via

npm i -D @open-wc/scoped-elements@next

Adds compatibility for lit with lit-html v2 and lit-element v3.

• This version does NOT work with lit-element v2 - please use Scoped Elements v1 for it

• Uses a CustomElementsRegistry instance for each component class instead of for each component instance. In case you need to have a registry for each component instance, you must override the registry get and set methods to bind the registry to the component instance

  /** @override */
  get registry() {
    return this.__registry;
  }
  
  /** @override */
  set registry(registry) {
    this.__registry = registry;
  }
  

• getScopedTagName became deprecated - use the native el.tagName instead

@open-wc/lit-helpers@next

You can get the prerelease via

npm i -D @open-wc/lit-helpers@next

• Removes directives from package
• the live directive is in the official lit package.
• the spread and spreadProps directives no longer work with the updated directive API of lit. They will need to be recreated and we will do this in lit-labs.
• import { /* ... */ } from '@open-wc/lit-helpers'; is now the only valid entrypoint

@open-wc/dev-server-hmr@next

You can get the prerelease via

npm i -D @open-wc/dev-server-hmr@next

• Update babel dependency to use @babel/plugin-syntax-import-assertions.

• Add a preset for the new lit package which will patch imports like import { LitElement } from 'lit';

  import { hmrPlugin, presets } from '@open-wc/dev-server-hmr';
  
  export default {
    plugins: [
      hmrPlugin({
        presets: [presets.lit],
      }),
    ],
  };
  

Service Worker strategy change

As our page grows so did what you needed to download when visiting our page. Our strategy was to make the full documentation site available for offline usage whenever you visited our website. That was fine when we had only a few pages but now an update can lead to our users downloading 10 MB even though you might only be interested in a single article. It also meant that the user would see the old cached version of the website until every single page was downloaded. So from today we are changing our strategy to

• caches only visited pages
• caches assets of visited pages (up to 100 files then it replaces older entries)
• on service worker activation it will reload the page if a newer version is available

In the future, we'll iterate on this pattern, and allow users to opt in to enabling offline mode for the entire website, or select parts of the website. This change however will drastically reduce the cache size and the time for you to see the new content.

--

Photo by Paul Robert on Unsplash