@lwc/module-resolver

What's Changed

The breaking changes in this release only impact TypeScript users; there is no change in runtime behavior, as compared to v7.2.6.

This release contains changes to the type signature of the @wire decorator, to enable better type checking of the provided values. Given @wire(adapter, config) prop, the types of config and prop now must match the types used by adapter. The type checking also successfully resolves reactive props (string starting with $) to the type used by the component.

In the example below, the component passes type checking with LWC v7, but has three new type errors in LWC v8.

type Config = { id: number }
type Book = { title: string, author: string }
declare const getBook: WireAdapterConstructor<Config, Book>

class Component extends LightningElement {
  bookId = 123
  authorName = 'Codey the Bear'

  // Valid: simple case
  @wire(getBook, { id: 123 }) valid?: Book
  // Valid: `bookId` on the component is a number
  @wire(getBook, {id: '$bookId'} as const) validReactiveProp?: Book
  // Invalid: `Author` is not `Book`
  @wire(getBook, { id: 123 }) invalidPropType?: Author
  // Invalid: `true` is not a number
  @wire(getBook, { id: true }) invalidConfigType: Book
  // Invalid: `authorName` prop on the component is not a number
  @wire(getBook, {id: '$authorName'} as const) invalidReactiveProp?: Book

Limitations

• Due to the way decorators are implemented in TypeScript, the type of the prop cannot be inferred from the wire adapter; you must provide an explicit type.

• To get the most accurate validation of your types, use const assertions on your config object. Without a const assertion, the type system cannot distinguish between a reactive prop (e.g. "$authorName") and a regular string (e.g. "Codey the Bear"). As a consequence, all values of type string are not type checked.

  • For example, for a config of type {id: number}, providing the object {id: "123"} will pass validation, but {id: "123"} as const will not.

• Due to the above constraints, the reported type errors can appear complex and hard to understand. They typically boil down to validating that your config object and prop type both match the type expected by the wire adapter.

What's Changed

• template-compiler: static-optimize on event listener object

What's Changed

• engine: Avoid invalid scope tokens entirely

What's Changed

• engine: Avoid non-string scope tokens

What's Changed

• template-compiler: Escape tag names

• template-compiler: Escape attribute names

What's Changed

• engine-core: Reduce fragment cache objects

• Fix light dom slot forwarding bug

What's Changed

• Optimize scoped ID for light/native

• Improve error for null/undefined iter values

• engine-core: Optimize getStylesheetsContent

• rollup-plugin: Add @lwc/shared dep

• Add flag to disable synthetic shadow

What's Changed

• engine-core: Gated slot forwarding fix

What's Changed

• Backport several validation fixes

What's Changed

• Revert "prevent prematurely cloning light dom slot vnodes"

What's Changed

• hydration: Only ignore mutated host attributes

What's Changed

• Do not error if abort controller for stylesheet does not exist @W-16189944

• Optimize initial render for nullish class

What's Changed

• engine-dom: Warn for insertBefore with 1 arg

• Add data-lwc-host-mutated during SSR

What's Changed

• perf-benchmarks: Add parseHTMLUnsafe polyfill

• template-compiler: Remove v6 engine support

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