Introducing Component-Level API Versioning for LWC

In Winter ’24, we introduced component-level API versioning for LWC component authors. This feature is designed to give you peace of mind that your components will continue to work throughout Salesforce major releases, while also allowing you to tap into new functionality and meaningful improvements in the framework itself.

If you’ve already written LWC components and shipped them on the Salesforce Platform, there is no action required on your part. However, if you are interested in how LWC works under the hood, or if you’d like to get the latest and greatest improvements to the speed and functionality of your LWC components, then read on.

The problem of versioning

Many JavaScript frameworks, such as React, Angular, and Vue, have a concept of versioning. For instance, you may install React version 17 and then later upgrade to React version 18.

This process typically follows Semantic Versioning, or SemVer. When a component author upgrades their framework version, this number tells them whether to expect breaking changes (major version) or just new features and bug fixes (minor and patch versions, respectively). After bumping a major version, the component author might test their app and ensure that it still works with the updated framework.

This system works fine for a general-purpose JavaScript framework, but it doesn’t work for the Salesforce Platform. At Salesforce, we have an evergreen cloud that takes away the pain of software upgrades from our customers: no tedious migrations, no manual security patches, no “click here to upgrade.” At the same time, we pride ourselves on our commitment to backward compatibility; we don’t want to needlessly break customer code when we ship a new release.

The LWC framework, like any software, has legacy features that we’d rather get rid of. However, experience has taught us that we cannot introduce observable changes (no matter how trivial!) without breaking at least some customers. So, due to Hyrum’s Law, we are unable to ship many new features, bug fixes, or performance improvements — even if the vast majority of customers would not be negatively affected.

Obviously, it’s not possible to simply never change LWC again, and to allow the platform to stagnate and decay. Our customers want new features, bug fixes, and enhancements — they just don’t want to be broken. How can we serve both needs at the same time?

Enter API versioning

API versioning is a familiar concept in the world of REST-based public APIs. In that context, it means exposing multiple versions to API consumers, so that consumers of the older API are not broken (e.g., /api/v1/search and /api/v2/search).

To leverage this concept for LWC, we are tweaking it slightly: instead of applying to REST endpoints, it applies to individual components running in the browser. This change applies to all customer-authored components running in Salesforce Lightning Experience, Experience Builder sites, and the Salesforce mobile app.

Component-level API versioning provides an explicit guarantee that, for a given component, the LWC framework will behave as it did for the Salesforce release corresponding to the API version for that component. Components using multiple API versions can happily coexist on the same page.

Note: This system is partially inspired by React v17’s ability to embed multiple versions of the framework in the same page. The difference is that, with LWC, each component has its own API version, and under the hood, the framework code is still the same.

To choose an API version, modify the apiVersion key in the *.js-meta.xml file corresponding to a component. For instance, for component.js, you would have a co-located component.js-meta.xml file like so:

In the above example, the API version is 58.0, which corresponds to the Summer ’23 Salesforce release. By setting the apiVersion to 58.0, this effectively says that the associated LWC component should behave as it did in Summer ’23. A full list of versions can be found on lwc.dev.

Under the hood, LWC will change how it parses, compiles, and executes the given component, preserving backward compatibility. New versions of the LWC framework will continue to honor older API versions.

The impact of API versioning

Starting with Winter ’24, all API versions of 58.0 and below will be treated by LWC as version 58.0 (aka Summer ’23). These components will continue to work exactly as they did in Summer ‘23, and no action is needed from component authors.

However, some bug fixes and performance improvements will only be available for components using API version 59.0 and above. In the future, some features will only be available for components using the latest API versions.

For example, API version 59.0 introduced obfuscated CSS scope tokens. This is a low-level technical detail of the framework that would only break a small number of components that rely on a known anti-pattern. To avoid breaking these components, API version 58.0 and below instructs the LWC framework to continue using the old format.

However, components on API version 59.0 and above will automatically use the new format. In addition, these components will enjoy up to 21% faster rendering of static SVGs — an optimization that the LWC framework could only make thanks to the new format. So, as a component author, you get faster LWC components, just by increasing a number!

How to upgrade your component API version

To upgrade your API version, we recommend the following steps:

Enable Lightning Debug Mode (available via “Advanced User Details” or Admin Setup).
Deploy your components and check for any warnings in the Salesforce CLI output. Fix these warnings.
Run your components in a sandbox, and check the browser DevTools console for any LWC warnings. Fix these warnings.
Bump the apiVersion in the *.js-meta.xml files for your components to the next-highest version.
Publish and enjoy!

In the future, if you find yourself several API versions behind, we recommend repeating steps 2 through 4. A warning in one API version could become an error in the next API version, so it’s vital to test each version. Plus, it’s typically easier to upgrade one at a time rather than all at once.

Note that not every breakage can be predicted with a clear warning. Some breakages may be due to subtle runtime changes. The framework will make a best-effort attempt to warn you of impending breakages, but not all runtime errors can be consistently predicted. So it’s best to thoroughly test your components when bumping the apiVersion, and to review the LWC breaking changes overview if you are unsure.

If you have a particularly troublesome component that’s hard to upgrade, feel free to independently version your components — i.e., use different versions for different components. Components with different API versions can coexist on the same page, within the same managed package, and within the same namespace (e.g., c/).

And if you’re concerned about risky changes or don’t have the time to test, then don’t worry! You can keep all your components on API version 58.0 or below, and they will continue to work as before. Following Salesforce’s API version retirement philosophy, we will strive to provide advance warning if we ever intend to retire old API versions (similar to the Salesforce Platform API version retirement).

Note that for many Salesforce customers, this pattern will already be familiar, since it mirrors the way API versioning has worked for many years in non-LWC contexts. (This is exactly the point!)

Which version of LWC should I use for my Jest and local tests?

If you are testing your components in a standalone Git repository using tools like @salesforce/sfdx-lwc-jest, we recommend updating your dependency in package.json to the latest version whenever possible, as you would for any other dependency.

For users of the LWC open-source framework in any other environment, the advice is the same: update the dependency in package.json at your earliest convenience.

Outside of Lightning Experience (e.g., in Jest), LWC will always run components with the latest API version corresponding to the version of LWC installed in your local repo. So in the case of Jest tests, you can treat this as an “advance warning” of new LWC behavior, rather than as a perfect simulation of Lightning Experience.

Summary

LWC API versioning is a great way to ensure backward compatibility for your existing components, while still allowing new components to gradually adopt new features and move away from legacy behavior.

For most customers, we hope that API versioning will be a seamless feature that you rarely have to think about. As long as you are following LWC component authoring best practices and using standard web APIs, you are very unlikely to experience breakages.

The good news is that your LWC components will get steadily faster and more standards-compliant with every release. All while maintaining backward compatibility!

We hope that you enjoy LWC API versioning, and we’re excited to see what kinds of components you build on our evolving platform.

Resources

About the authors

Nolan Lawson is a Principal Member of Technical Staff on the Lightning Web Components framework team, where he focuses on performance, accessibility, and web standards.

Diana Widjaja is a Lead Technical Writer who has been writing for Lightning Web Components, Base Lightning Components, Lightning Data Service, and many other teams.