<commit_before>---
title: Upgrade guide
eleventyNavigation:
  key: Upgrade guide
  parent: Releases
  order: 3
---

## Overview

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.
1. Loading `polyfill-support` script when loading the webcomponents polyfills.
1. Updating any custom directive implementations to use new class-based API and associated helpers
1. Updating code to renamed APIs.
1. Adapting to minor breaking changes, mostly in uncommon cases.

The following sections will go through each of these changes in detail.

## Update packages and import paths

### Use the `lit` package

Lit 2.0 ships with a one-stop-shop `lit` package, which consolidates `lit-html` and `lit-element` into an easy-to-use package. Use the following commands to upgrade:

```sh
npm uninstall lit-element lit-html
npm install lit
```

And re-write your module imports appropriately:

From:
```js
import {LitElement, html} from `lit-element`;
```
To:
```js
import {LitElement, html} from `lit`;
```

Although the `lit-element@^3` and `lit-html@^2` packages should be largely backward-compatible, we recommend updating to the `lit` package as the other packages are moving towards eventual deprecation.

### Update decorator imports

The previous version of `lit-element` exported all TypeScript decorators from the main module. In Lit 2.0, these have been moved to a separate module, to enable smaller bundle sizes when the decorators are unused.

From:
```js
import {property, customElement} from `lit-element`;
```
To:
```js
import {property, customElement} from `lit/decorators.js`;
```

### Update directive imports

Built-in lit-html directives are also now exported from the `lit` package.

From:
```js
import {repeat} from `lit-html/directives/repeat.js`;
```
To:
```js
import {repeat} from `lit/decorators/repeat.js`;
```

## Load `polyfill-support` when using webcomponents polyfills

Lit 2.0 still supports the same browsers down to IE11. However, given the broad adoption of Web Components APIs in modern browsers, we have taken the opportunity to move all of the code required for interfacing with the `webcomponents` polyfills out of the core libraries and into an opt-in support file, so that the tax for supporting older browsers is only paid when required.

In general, any time you use the `webcomponents` polyfills, you should also load the `lit/polyfill-support.js` support file once on the page, similar to a polyfill. For example:

```html
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js">
<script src="node_modules/lit/platform-support.js">
```

If using [`@web/test-runner`](https://modern-web.dev/docs/test-runner/overview/) or [`@web/dev-server`](https://modern-web.dev/docs/dev-server/overview/) with the [`legacyPlugin`](https://modern-web.dev/docs/dev-server/plugins/legacy/) for development, adding the following configuration to your `web-test-runner.config.js` or `web-dev-server.config.js` file will configure it to automatically inject the support file when needed:

```js
export default {
  ...
  plugins: [
    legacyPlugin({
      polyfills: {
        webcomponents: true,
        custom: [
          {
            name: 'lit-polyfill-support',
            path: 'node_modules/lit/polyfill-support.js',
            test: "!('attachShadow' in Element.prototype)",
            module: false,
          },
        ],
      },<commit_msg>Upgrade guide: fix typo (#313)<commit_after>---
title: Upgrade guide
eleventyNavigation:
  key: Upgrade guide
  parent: Releases
  order: 3
---

## Overview

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.
1. Loading `polyfill-support` script when loading the webcomponents polyfills.
1. Updating any custom directive implementations to use new class-based API and associated helpers
1. Updating code to renamed APIs.
1. Adapting to minor breaking changes, mostly in uncommon cases.

The following sections will go through each of these changes in detail.

## Update packages and import paths

### Use the `lit` package

Lit 2.0 ships with a one-stop-shop `lit` package, which consolidates `lit-html` and `lit-element` into an easy-to-use package. Use the following commands to upgrade:

```sh
npm uninstall lit-element lit-html
npm install lit
```

And re-write your module imports appropriately:

From:
```js
import {LitElement, html} from `lit-element`;
```
To:
```js
import {LitElement, html} from `lit`;
```

Although the `lit-element@^3` and `lit-html@^2` packages should be largely backward-compatible, we recommend updating to the `lit` package as the other packages are moving towards eventual deprecation.

### Update decorator imports

The previous version of `lit-element` exported all TypeScript decorators from the main module. In Lit 2.0, these have been moved to a separate module, to enable smaller bundle sizes when the decorators are unused.

From:
```js
import {property, customElement} from `lit-element`;
```
To:
```js
import {property, customElement} from `lit/decorators.js`;
```

### Update directive imports

Built-in lit-html directives are also now exported from the `lit` package.

From:
```js
import {repeat} from `lit-html/directives/repeat.js`;
```
To:
```js
import {repeat} from `lit/directives/repeat.js`;
```

## Load `polyfill-support` when using webcomponents polyfills

Lit 2.0 still supports the same browsers down to IE11. However, given the broad adoption of Web Components APIs in modern browsers, we have taken the opportunity to move all of the code required for interfacing with the `webcomponents` polyfills out of the core libraries and into an opt-in support file, so that the tax for supporting older browsers is only paid when required.

In general, any time you use the `webcomponents` polyfills, you should also load the `lit/polyfill-support.js` support file once on the page, similar to a polyfill. For example:

```html
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js">
<script src="node_modules/lit/platform-support.js">
```

If using [`@web/test-runner`](https://modern-web.dev/docs/test-runner/overview/) or [`@web/dev-server`](https://modern-web.dev/docs/dev-server/overview/) with the [`legacyPlugin`](https://modern-web.dev/docs/dev-server/plugins/legacy/) for development, adding the following configuration to your `web-test-runner.config.js` or `web-dev-server.config.js` file will configure it to automatically inject the support file when needed:

```js
export default {
  ...
  plugins: [
    legacyPlugin({
      polyfills: {
        webcomponents: true,
        custom: [
          {
            name: 'lit-polyfill-support',
            path: 'node_modules/lit/polyfill-support.js',
            test: "!('attachShadow' in Element.prototype)",
            module: false,
          },
        ],
      },
{'fraction_non_alphanumeric': 0.10195860536185582, 'fraction_numerical': 0.006528684539519378, 'mean_word_length': 4.031446540880503, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3745639', 'n_tokens_mistral': 2121, 'n_tokens_neox': 1984, 'n_words': 848}