API Versioning
| AVAILABLE API VERSIONS |
|---|
| Available in LWC API v59.0 and later |
Beginning in Winter '24, LWC supports versioning for custom components. When a component specifies a version, the component then depends on that specific version of a Salesforce release. Every HTML, CSS, and JS file of a component corresponds to one API version. The API version tells the LWC framework to behave as it did for the Salesforce release corresponding to the specified API version for that component.
LWC open source follows semantic versioning (semver) characteristics. See LWC Open Source: LWC Versioning.
While LWC on the Salesforce platform uses the same code base as LWC open source, the version of LWC on the Salesforce platform is 3-6 months behind the open source version. For example, LWC OSS released v3.0.0 in June 2023 and the same was available to external Salesforce platform developers as part of the Winter '24 release.
As of Winter '24, all API versions of 58.0 and earlier correspond to 58.0 (Summer '23). If you set the API version to a value lower than 58.0, LWC uses version 58.0 by default.
To apply bug fixes and new functionality that are tied to a later API version, upgrade your component's API version.
A warning in an API version can become an error in the next API version. We recommend that you test each version and upgrade one version at a time.
To upgrade your component API version:
- Publish your component. Fix any warnings in the SFDX console.
- Run your component in a sandbox. Fix any warnings in the browser DevTools console.
- Increment the
apiVersionin the*.js-meta.xmlfile for your component to the next version. - Publish your component again and verify that you no longer see any warnings.
For example, if you specify an apiVersion value of 58.0, your component continues to behave as it did in API version 58.0 (Summer '23). Your component doesn't include the bug fixes and enhancements that are introduced in version 59.0 and later.
Regardless of apiVersion, custom components always use the latest version of Lightning Data Service and base Lightning components.
Component-level breaking changes apply to custom components for Lightning Experience, Experience Builder sites, and the Salesforce mobile app.
LWC developers who use LWC outside of the Salesforce platform are impacted by additional breaking changes. For more information, see LWC OSS v6.0.0.
As of Summer '24, ElementInternals support is available as a versioned feature. To see what's changed in LWC in the latest Salesforce release, see the release notes. Changes apply to all apiVersion values unless otherwise stated.
Here's how Salesforce releases map to LWC API versions and LWC OSS versions.
| Salesforce Release | LWC API Version | LWC OSS |
|---|---|---|
| Summer '23 | 58.0 | v2.50.0 and earlier |
| Winter '24 | 59.0 | v3.0.0 |
| Spring '24 | 60.0* | v5.0.0 |
| Summer '24 | 61.0 | v6.0.0 |
* LWC API version 60.0 also includes changes from LWC OSS v4.0.0.
Consider these guidelines when working with LWC API versioning.
- If you use an
apiVersionthat's earlier than the earliest known LWC API version, LWC uses the earliest known version. For example, if the earliest known version is 58.0 and you provide 57.0, LWC uses 58.0. - If the latest LWC version is 61.0 and you provide 62.0, then LWC uses 61.0.
- LWC API versioning isn't available for Aura components and LWR.
- LWC API versioning is available only for custom components in Lightning Experience or Experience Builder sites that include the
*.js-meta.xmlfile. - Custom components in LWR use the latest LWC API version when not running in Lightning Experience or Experience Builder sites.
- Components on the same page or within the same managed package can have different API versions.