Lightning Web Components

The @lwc/ssr-compiler is an experimental package that provides a compiler specifically designed for server-side rendering (SSR) of Lightning Web Components.

Warning: This package is currently experimental and its API or behavior may change or break without notice.

The @lwc/ssr-client-utils package provides utility functions designed for working with server-side rendered (SSR) Lightning Web Components.

Warning: This package is currently experimental. The API and functionality are subject to change and may break without notice.

Once @lwc/aria-reflection is imported, it applies the polyfill globally to Element.prototype. This allows you to interact with ARIA attributes either via setAttribute/getAttribute or via direct property access. The two methods are reflected: changing the attribute updates the property, and changing the property updates the attribute.

Example of bidirectional reflection:

element.setAttribute('aria-pressed', 'true');
console.log(element.ariaPressed); // true

element.ariaPressed = false;
console.log(element.getAttribute('aria-pressed')); // false

LWC includes several experimental APIs related to Signals and Context. These require the ENABLE_EXPERIMENTAL_SIGNALS feature to be enabled.

Warning: Many of these APIs are marked as 'Not intended for external use' and may change or break without notice. Use them with caution in production environments.

The EventTarget polyfill ensures that event management methods are available across different browser environments.

In modern browsers, addEventListener(), removeEventListener(), and dispatchEvent() are part of the EventTarget interface. However, in legacy environments like IE11, these methods are defined on the Node interface instead. To maintain compatibility, the polyfill detects if EventTarget is undefined and, if so, patches Node.prototype to provide these methods.

Additionally, the polyfill intercepts listener invocations via addEventListener() to filter events based on their bubbles and composed configuration properties.

LWC module resolution is configured using a lwc.config.json file or an lwc key in package.json. The resolver iterates through the modules array and returns the first match.

There are three types of module records:

1. Alias module record: Maps a specific name to a specific file path.
2. Directory module record: Specifies a folder where LWC modules are resolved based on an opinionated folder structure.
3. NPM package module record: Indicates an NPM package that exposes LWC modules.

Example configuration in lwc.config.json:

{
    "modules": [
        {
            "name": "ui/button",
            "path": "src/modules/ui/button/button.js"
        },
        {
            "dir": "src/modules"
        },
        {
            "npm": "@ui/components"
        }
    ]
}

When using the Synthetic Shadow Root, be aware of the following behavioral differences compared to native Shadow DOM:

• <slot> Default Content: The default content for <slot> elements is always empty.
• slotchange Event Behavior: The slotchange event is only available directly on the <slot> element and does not bubble. This restriction is implemented to avoid the performance overhead of using MutationObserver for all slots. The engine only triggers this event when it detects interest, saving CPU cycles.
• MutationObserver Memory Leaks: If you use MutationObserver to watch changes in a DOM tree, you must manually disconnect it to prevent memory leaks.
• Observation Scope: A component can only observe mutations within its own template. It cannot observe mutations occurring within the shadow tree of other custom elements.

The plugin performs several key transformations to prepare LWC components for the engine:

Decorator Transformations

• @api is transformed into publicProperties and publicMethods static properties.
• @wire is transformed into a wire static property.
• @track is transformed into a track static property.

LWC Component Class Sugar

• Lifecycle Hooks: Validates and checks for misspelled lifecycle hooks.
• Template Injection: Automatically imports and injects a render method from a collocated template if the component class does not explicitly implement one.

Optimizations

• If the compiler injects a default template into a component, the plugin wires the template style to that component.