@lwc/shared

LWC v3.0.0 contains breaking changes. Please read carefully below if you are upgrading from v2 to v3.

ℹ️ LWC v3 corresponds to Salesforce release Winter '24 (API version 59).

Breaking Changes

Remove support for IE11 and other legacy browsers

ℹ️ This change applies to all LWC components and the entire Salesforce Lightning platform.

Internet Explorer is no longer supported. If you are using the Salesforce Lightning platform, please refer to Supported Browsers and Devices for Lightning Experience and Ending Support for IE11 on the Lightning Platform.

• breaking

  Remove compat support (BREAKING CHANGE)

CSS scope tokens have changed

ℹ️ On the Salesforce Lightning platform, this change only applies to components with an API version of 59 or above.

To scope CSS, LWC automatically adds attributes and classes to DOM elements. These attributes and classes should be considered internal implementation details of the framework, and developers should not rely on them.

In this release, the scope tokens have changed. Before, they used a format like c-foo_foo (for the <c-foo> component). Now, they use a format like lwc-<hash>. For instance:

Old format:

<c-foo c-foo_foo-host>
  <div c-foo_foo></div>
</c-foo>

New format:

<c-foo lwc-1hl7358i549-host>
  <div lwc-1hl7358i549></div>
</c-foo>

If you are relying on these attributes/classes in your tests, or for this.template.querySelector(), please avoid relying on them, as they could change at any time. Instead of this.template.querySelector(), you can also use lwc:ref.

This change was made as part of a performance improvement to optimize SVG rendering.

• breaking

  Add API versioning (BREAKING CHANGE)

HTML template parsing is stricter

ℹ️ On the Salesforce Lightning platform, this change only applies to components with an API version of 59 or above.

Previously, certain HTML syntax errors were ignored by the LWC compiler but emitted a warning. Now, these syntax errors will result in a failed component compilation.

The most common syntax error is the following (in component HTML):

<template>
</template>
</template>

Note the double-ending </template> tag. Previously, this would emit a warning, but it now emits an error.

Other possible syntax errors include:

Unclosed elements:

<template>
  <div>
</template>

Invalid empty tags:

<template>
  <section/>
</template>

Stranded close tags:

</template>

Please fix any syntax warnings in LWC v2 before upgrading to LWC v3 to avoid this issue. We have a codemod that can automatically do this for you.

• breaking

  Add API versioning (BREAKING CHANGE)

Implicit hydration is removed for CustomElementConstructor

ℹ️ This change only affects consumers of the CustomElementConstructor API.

The CustomElementConstructor API now creates custom elements that do not attempt to do implicit hydration (i.e. treating the component as if it were generated by Server-Side Rendering). This change should be a mostly positive one, as it will avoid a class of warnings that affected developers who were using standalone LWC components as custom elements.

• breaking

  Remove implicit hydration (BREAKING CHANGE)

Remove legacy package files and reorganize lwc package

ℹ️ This change only affects consumers of the lwc or @lwc/* open-source packages from npm.

Previously, the LWC packages published to npm used a bespoke format for each package. Some consumers may have taken a reliance on the quirks of these package structures, for instance:

import '@lwc/compiler/dist/commonjs/transformers/transformer.js'
import '@lwc/engine-dom/dist/engine-dom.js'
import '@lwc/synthetic-shadow/dist/synthetic-shadow.js'

Instead, consumers are encouraged to avoid deep-importing from these packages:

import '@lwc/compiler'
import '@lwc/engine-dom'
import '@lwc/synthetic-shadow'

Also, the lwc package used to contain transformed versions of various packages (e.g. IIFE format, UMD format, minified format, etc.).

Now, all packages export a single CommonJS and ES Module file, and the lwc package merely re-exports these other packages. If you need these packages in a special format (IIFE, UMD, minified, etc.), you are encouraged to run your own bundler/minifier to accomplish this, e.g. Rollup and Terser.

• breaking

  Remove legacy dist files (BREAKING CHANGE)

• breaking

  Make lwc re-export other packages (BREAKING CHANGE)