@lwc/engine-server

What's Changed

• engine-dom: Warn for insertBefore with 1 arg

• Add data-lwc-host-mutated during SSR

LWC v7.0.0 contains breaking changes. Please read carefully below if you are upgrading from v6.

If you are upgrading from v5, please upgrade to v6 first.

New features

• Class object binding for more ergonomic classes in templates

• this.style for a more ergonomic way to change component styles at runtime

• this.hostElement for an alternative to this.template.host that works in light DOM

Breaking changes

Class object binding

Class object binding is a new feature that makes it more ergonomic to render class attributes in your LWC components. As part of this feature, class rendering has changed for some uncommon use cases.

If you are using a dynamic class in your template:

<template>
  <div class={myClass}></div>
</template>

Then the rendering of this class may change if you were previously defining myClass as something other than a string, null, or undefined.

For example, consider if myClass is a boolean:

export default class extends LightningElement {
  myClass = false
}

Old behavior:

This renders:

<div class="false"></div>

New behavior:

<div class=""></div>

This change applies to booleans, numbers, functions, arrays, and objects. Below is a table summarizing the change:

In short:

• breaking

  Booleans, numbers, and functions are no longer directly stringified, but are stripped instead.

• breaking

  Arrays and objects are no longer stringified, but instead follow class object binding semantics.

This may break a component if it is using a CSS selector like these:

.false {}
.true {}
[class="1"] {}

Or if it is using querySelector or other traversal techniques that rely on the class name:

this.template.querySelector('.false')
this.template.querySelector('.true')
this.template.querySelector('[class="1"]')

In rare cases, this can also cause breakages across component boundaries. For example, if you have a global stylesheet relying on light DOM or synthetic shadow DOM, and thus the ability to pierce inside of components you don't own, then the above CSS selectors would break in that case as well.

To resolve any breakages:

• breaking

  Avoid anti-patterns for styling components.

• breaking

  In cases where you want to render a value as a string (e.g. class="false" or class="1"), convert it to a string using String(value).

This change may also require updating snapshots, e.g. in Jest tests.

New this.style property

Components can now access their CSSStyleDeclaration using this.style:

renderedCallback() {
  this.style.color = 'red'
}

This is a breaking change if the component uses this.style as an expando:

renderedCallback() {
  if (!this.style) {
    this.style = "foo"
  }
}

In the above case, the component author may assume that this.style is initially undefined, and then set it to a new value ("foo"). After this change, the above code will not work as expected, because this.style is initially truthy rather than undefined.

To resolve this, set a class property on the component, initialized to undefined, rather than using an expando:

+ style = undefined
  
  renderedCallback() {
    if (!this.style) {
      this.style = "foo"
    }
  }

You may also rename your this.style expando to something else (e.g. this.customStyle).

New this.hostElement property

Components can now access this.hostElement as a convenient alternative to this.template.host:

renderedCallback() {
  console.log(this.template.host) // <x-component>
  console.log(this.hostElement)   // <x-component>
}

Additionally, this works in light DOM components to access the "host" element (similar to the :host CSS pseudo-class in light DOM scoped styles). This provides an ergonomic way to access the root HTMLElement object in either light DOM or shadow DOM components.

Similar to the new this.style property, this is a breaking change if you are using this.hostElement already as an expando. Refer to the this.style release notes for a resolution.

Improved TypeScript types

The TypeScript definitions for the lwc package are greatly improved, to more closely match the ground truth of the actual APIs for LightningElement, createElement, etc. at runtime. You may need to adjust your TypeScript code or version to adapt to the new typings.

Summary

• breaking

  The minimum supported version of TypeScript is v5.4.5.

• breaking

  The only supported compiler target is "ESNext".

• breaking

  ContextValue has been renamed to WireContextValue.

• breaking

  ContextConsumer has been renamed to WireContextConsumer.

• breaking

  Contextualizer has been renamed to WireContextProvider.

• breaking

  StylesheetFactory has been renamed to Stylesheet.

• breaking

  StylesheetFactories has been renamed to Stylesheets.

• breaking

  StringKeyedRecord has been removed. Instead, use the type Record<string, any>.

• breaking

  ShadowSupportMode has been removed. Instead, use the string values "any", "reset", or "native".

• breaking

  WireAdapter is now a generic type with a default type parameter.

• breaking

  WireAdapterConstructor is now a generic type with a default type parameter.

• breaking

  All decorators can now be used with the new decorator implementation introduced in TypeScript v5 as well as the old, experimental implementation.

• breaking

  this.template is now possibly null, reflecting the state for components using light DOM.

• breaking

  this.template.host in a LightningElement is now typed as HTMLElement, rather than the broader Element.

• breaking

  The return type of createElement has been updated to reflect the fact that the element created contains the @api-decorated props from the component definition.

  • A new helper type, LightningHTMLElement, has been introduced to provide an easy way of accessing the return type.

    const cmp: LightningHTMLElement<MyComponent> = createElement('my-component', { is: MyComponent });

  • WARNING: Due to limitations of TypeScript, this new type incorrectly contains all props defined on the component, not just decorated props. Only decorated props are accessible at runtime.

• breaking

  Importing from "lwc" now provides module definitions for HTML/CSS imports. The module definitions are also available by directly importing a new package, @lwc/types.

Common breakages and fixes

@lwc/template-compiler API changes

Due to a refactoring of the @lwc/compiler and @lwc/template-compiler packages, the @lwc/template-compiler compile function now requires the component's file name (i.e. the namespace and name options) when compiling the template.

To resolve the breaking change, add the new options. For example:

import { compile } from '@lwc/template-compiler'

compile({
  ...previousOptions,
  // Assuming the component is `<x-foo>`:
  namespace: 'x',
  name: 'foo',
})

What's Changed

• lightning-element: Expose hostElement property

• Put this.hostElement behind API version 62

• Allow access to host CSSStyleDeclaration via this.style

• Template class object binding

• types: Update types for v7

What's Changed

• Lwc compiler errors on .jsx/.tsx files

• New compiler targeting SSR

• playground: Add important features to playground @W-15545976

Observable changes

HTML elements with class and style attributes may render with additional whitespace. This is due to an optimization to improve the render time of Lightning Web Components.

This change is exactly the same as what we've reported in previous releases, and can be fixed by avoiding anti-patterns for styling components. E.g.:

/* Don’t do this */
document.querySelector('[class="highlight yellow"]');
/* Do this instead */
document.querySelector(".highlight.yellow");

The difference now is that this change may be seen in more components than before.

What's Changed

• Apply static parts optimization to dynamic attributes

• Fix iframe onload with static content optimization

• Remove unnecessary nullish coalescing

• Apply static parts optimization to dynamic style

• synthetic-shadow: Optimize recursivelySetShadowResolver

• template-compiler: Support key in static content

• Optimize createUpgradableConstructor

• Apply static parts optimization to dynamic class attributes

• Support arguments for FACE callbacks

• engine-core: Fix warnings for invalid keys

• engine-core: Optimize patchClassAttribute

• Error accessing tagName on fragment

• Apply static parts optimization to dynamic text

• Children and childNodes not returning top-level slotted children

• Add signals as dependency

What's Changed

• template-compiler: Avoid mutating the ast when binding complex template expressions

• Event listener not being invoked for native web components

• Support generating inlined sourcemaps when transforming js file…

• template-compiler: Avoid discarding text content whitespace for complex expressions

Contains signal implementation in LWC and a few other bug fixes.

What's Changed

• Signals implementation v1

• Add reporting for shadowSupportMode

• Add default exports to lwc @W-13710298

What's Changed

• Use more helpful error message for invalid render() return value @W-14785069

• Allow computed properties in @wire if they are constants or primitives @W-14785085

LWC v6.0.0 contains breaking changes. Please read carefully below if you are upgrading from v5.

If you are upgrading from v4, please upgrade to v5 first.

Summary of new features

• Form-Associated Custom Elements (FACE) and Element Internals are now supported.

Breaking changes

Native custom element lifecycle

Previous versions of LWC used a synthetic (polyfill) system to call the connectedCallback and disconnectedCallback component lifecycle hooks. This was originally designed for legacy browsers such as Internet Explorer 11. Such browsers are no longer supported, and LWC v6 uses the native browser APIs instead.

This change may affect the firing of connectedCallback and disconnectedCallback hooks in your components, since the previous implementation did not perfectly align with the browser standard. Most commonly, this will occur in unit tests, or when manually creating components using the lwc.createElement() API. The new behavior also fixes common memory leaks caused by disconnectedCallback not firing consistently.

Native custom element lifecycle also unlocks support for Form-Associated Custom Elements (FACE) and Element Internals.

Changes you may see to connectedCallback and disconnectedCallback behavior:

New behavior when disconnected from the DOM

LWC components now only fire connectedCallback when they are actually connected to the DOM. If they are disconnected from the DOM (i.e. they are not inside the document), then connectedCallback will not fire.

For instance, if you are testing for an event to be fired from a connectedCallback, this would previously work:

export default class Foo extends LightningElement {
  connectedCallback() {
    this.dispatchEvent(new CustomEvent('foo', { bubbles: true, composed: true }))
  }
}

const element = createElement('x-foo', { is: Foo })
const div = document.createElement('div')
div.addEventListener('foo', () => {
  console.log('received foo event!')
})
div.appendChild(element) // triggers connectedCallback

In the above example, received foo event! would be logged to the console.

After this change, the above no longer triggers the connectedCallback, nor the event.

Instead, you must ensure the element is connected to the DOM:

document.body.appendChild(div)

Once the element is in the DOM tree, connectedCallback will fire as expected.

New error behavior

Errors thrown by connectedCallbacks and disconnectedCallback are dispatched globally, rather than locally when elements are added/removed from the DOM.

For example, let's say you have a component that throws an error in connectedCallback:

export default class Foo extends LightningElement {
  connectedCallback() {
      throw new Error('foo')
  }
}

And then you expect to be able to catch the error synchronously on appendChild:

const element = lwc.createElement('x-foo', { is: Foo })
try {
  document.body.appendChild(element)
} catch (error) {
  console.log('caught error', error)
}

• breaking

  Old behavior: the error is caught.

• breaking

  New behavior: the error is uncaught.

The solution is to use a global error listener:

const listener = (error) => {
  console.log('Caught error', error)
}
try {
  window.addEventListener('error', listener)
  document.body.appendChild(element);
} finally {
  window.removeEventListener('error', listener)
}

If you're using @lwc/jest-*, then you can use the new toThrowInConnectedCallback API which will handle this logic for you.

New timing behavior in native shadow DOM

The timing of connectedCallback has changed slightly to align with native browser standards, when using native shadow DOM.

For example, the timing of when connectedCallback fires in child components relative to parent components has changed. Consider this DOM tree:

<x-a>
  #shadow-root
  | <x-a-child>
</x-a>
<x-b>
  #shadow-root
  | <x-b-child>
</x-b>
<x-c>
  #shadow-root
  | <x-c-child>
</x-c>

Old behavior: the order of connectedCallbacks firing is:

• breaking

  x-a

• breaking

  x-b

• breaking

  x-c

• breaking

  x-c-child

• breaking

  x-b-child

• breaking

  x-a-child

New behavior: the order of connectedCallbacks firing is:

• breaking

  x-a

• breaking

  x-a-child

• breaking

  x-b

• breaking

  x-b-child

• breaking

  x-c

• breaking

  x-c-child

Note that, with the new behavior, connectedCallback fires in standard DOM depth-first tree-traversal order. (The old behavior was defined by the synthetic lifecycle polyfill, and did not follow the standard.)

The relative timing of renderedCallback has also changed due the new native connectedCallback timing. For example, consider this DOM tree:

<x-grandparent>
  <x-parent>
    <x-child></x-child>
  </x-parent>
</x-grandparent>

(Note that, in the above example, the <x-parent> and <x-child> are slotted, not part of the shadow roots of their containers.)

Old behavior: the order of lifecycle hooks firing is (example):

New behavior: the order of lifecycle hooks firing is (example):

Note that the above only applies to native shadow DOM. In synthetic shadow DOM, the ordering is the same, regardless of native vs synthetic custom element lifecycle (example). The same is true of light DOM (example).

In general, your components should not rely on the particular timing of connectedCallback or renderedCallback across components. In case they do, please update to match the new timing behavior, or make your code agnostic to any particular timing.

Note that the timing of disconnectedCallback has not changed, except as noted elsewhere in these release notes.

Shadow roots may be null after appending to disconnected elements

Consider this case:

<!-- app.html -->
<template>
  <x-child></x-child>
</template>

const elm = createElement("x-app", { is: App })
const div = document.createElement('div')
div.appendChild(elm)

console.log(elm.shadowRoot.querySelector('x-child'))

Old behavior: logs the <x-child> component, because the div.appendChild triggered the rendering of the child element.

New behavior: logs null, because div is disconnected from the DOM, preventing triggering of rendering.

The resolution is to append the element to an element that is actually connected to the DOM. For example, in the above case:

document.body.appendChild(div);

New timing behavior during list rendering

Before LWC v6, certain scenarios with for:each would not result in connectedCallback/disconnectedCallback firing on components inside the iteration, even if the components were actually disconnected and re-connected to the DOM (for example, during list reordering).

In LWC v6, connectedCallback/disconnectedCallback will accurately fire to reflect that the underlying framework has removed and re-inserted elements into the DOM. This may be disruptive for components that do not correctly handle additional connectedCallback/disconnectedCallback invocations, or that have significant performance overhead for these callbacks.

For example, if you have the iteration:

<template for:each={items} for:item="item">
  <x-item key={item}></x-item>
</template>

... and if the items array is originally [1, 2, 3, 4] and later changes to [3, 4, 2, 1], then you would see the following callbacks being invoked after the list order changes:

Old behavior: none of connectedCallback, disconnectedCallback, nor renderedCallback fire after reordering. (Demo)

New behavior: disconnectedCallback fires and then connectedCallback fires for list items 1 and 2 after reordering, because these items have been removed and re-inserted into the end of the list by the LWC framework. (Demo)

This also affects renderedCallback. Previously, you may have relied on renderedCallback for your setup logic and disconnectedCallback for your teardown logic. (For example: setting up event listeners or subscribing to a store.) Previously, this might work for some use cases. However, in LWC v6, your component may fire disconnectedCallback and then connectedCallback if it is inside of a list that is reordered – without firing renderedCallback (if the data bindings inside the component did not change).

For example, consider a list that is reordered from [1, 2] to [2, 1]. In both cases, before reordering, connectedCallback and renderedCallback are fired for items 1 and 2. However, after reordering, the following occurs:

Old behavior: no lifecycle callbacks fire after reordering. (Demo)

New behavior: disconnectedCallback fires and then connectedCallback fires for item 1. Additionally, renderedCallback fires for item 1 but does not fire for its children. (Demo)

A best practice is to do your setup logic in connectedCallback and teardown logic in disconnectedCallback. These two callbacks are perfect mirrors of each other – unlike renderedCallback, which may fire multiple times if the component data changes, and may not fire during a simple list reordering.

Fixed light DOM slot remapping

In previous versions of LWC, light DOM <slot>s do not correctly remap with different names. This bug is fixed in LWC v6, but it may cause a breaking change if you rely on quirks of the previous behavior.

The breaking changes are:

Slot attributes are no longer rendered

In LWC, light DOM slots are virtualized. This means that they do not rely on the native browser <slot> elements or slot attributes at runtime, when the component is actually rendered to the DOM.

Previously, your light DOM elements may have rendered with actual slot attributes. As of LWC v6, these slot attributes will not render. For example, consider this template:

<template>
    <!-- this child is light DOM -->
    <x-child>
        <div slot="foo">hello</div>
    </x-child>
</template>

Previously this would render to the DOM as (demo):

<!-- Previous rendered content -->
<div slot="foo">hello</div>

In LWC v6, this renders as (demo):

<!-- New rendered content -->
<div>hello</div>

If you are relying on the presence of the slot attribute (e.g. in a CSS selector or using this.querySelector()), then your code may break because the slot attribute is no longer present in the rendered DOM.

For light DOM components, you are recommended to avoid CSS selectors or this.querySelector() to match based on the slot attribute. Instead, you can use lwc:ref or choose another CSS selector.

For example, do not rely on CSS selectors like this:

// Don't do this
const foo = this.querySelector('[slot="foo"]');

Instead, use lwc:ref:

<x-child>
    <div slot="foo" lwc:ref="foo">hello</div>
</x-child>

const foo = this.refs.foo;

This may also change your Jest snapshots, which will need to be updated.

Strict light DOM slot forwarding

In previous versions of LWC, light DOM components that "wrap" a shadow DOM component were able to forward to the correct slot in the shadow DOM component without explicitly including a slot attribute.

For example, you may have a light DOM component like this:

<!-- x-slottable-light -->
<template lwc:render-mode=light>
  <x-slottable-shadow>
    <slot name="foo"></slot>
    <slot></slot>
  </x-slottable-shadow>
</template>

In LWC v5, this would forward the foo and default slots from <x-slottable-light> into <x-slottable-shadow>. However, this is actually a mistake, because proper slot forwarding should require a slot attribute on the <slot> element:

 <!-- x-slottable-light -->
 <template lwc:render-mode=light>
   <x-slottable-shadow>
-     <slot name="foo"></slot>
+     <slot name="foo" slot="foo"></slot>
     <slot></slot>
   </x-slottable-shadow>
 </template>

In LWC v6, you must update your code to use the proper slot attribute as shown above, or else the slotted content will not render correctly.

• breaking

  Demo in LWC v5 (working but should not work)

• breaking

  Demo in LWC v6 (non-working)

• breaking

  Demo in LWC v6 with corrected code (working)

Lifecycle callbacks accurately fire during list rendering

Before LWC v6, certain scenarios in list rendering would not result in connectedCallback/disconnectedCallback firing on components inside the list, even if the components were actually disconnected and re-connected to the DOM (for example, during list reordering).

In LWC v6, connectedCallback/disconnectedCallback will accurately fire to reflect that the underlying framework has removed and re-inserted elements into the DOM. This may be disruptive for components that do not correctly handle additional connectedCallback/disconnectedCallback invocations, or that have significant performance overhead for these callbacks.

For example, if you have the list:

<template for:each={items} for:item="item">
  <x-item uid={item} key={item}></x-item>
</template>

... and if items is originally [1, 2, 3, 4] and later changes to [3, 4, 2, 1]

Demo of LWC v6 behavior compared to LWC v5 behavior.

Standard shadowrootmode attribute in SSR

In SSR, the attribute used to mark declarative shadow DOM roots has changed to match the latest browser standards. Instead of shadowroot, the attribute is now shadowrootmode.

This may be a breaking change for you if you have a polyfill that is detecting the shadowroot attribute rather than shadowrootmode. It will also change your Jest snapshots, which will need to be updated.

Old format:

<x-foo>
  <template shadowroot="open">
    <div>Hello world</div>
  </template>
</x-foo>

New format:

 <x-foo>
-  <template shadowroot="open">
+  <template shadowrootmode="open">
     <div>Hello world</div>
   </template>
 </x-foo>

All changes

• engine-dom: Use native lifecycle callbacks

• engine-server: Use standard shadowrootmode attribute

What's Changed

• template-compiler: Exclude comments from static parts when lwc:preserve-comments is disabled

What's Changed

• Log shadow mode through engine reporting API

• Add flag for forced shadow migrate mode

What's Changed

• Remove string.prototype.matchAll polyfill