API Versioning

AVAILABLE API VERSIONS
Available in 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 the 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 API version for that component.

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. LWC open source follows semantic versioning (semver) characteristics. See LWC Open Source: LWC Versioning.

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:

  1. Publish your component. Fix any warnings in the SFDX console.
  2. Run your component in a sandbox. Fix any warnings in the browser DevTools console.
  3. Increment the apiVersion in the *.js-meta.xml file for your component to the next version.
  4. 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).

Component-level breaking changes apply to custom components for Lightning Experience and Experience Builder sites. To implement these changes in your components, upgrade the apiVersion to 59.0.

In Winter '24, there aren't any new LWC features that correspond to an apiVersion value. To see what's changed in LWC in the latest Salesforce release that apply to all apiVersion values, see the release notes.

Here's how Salesforce releases map to LWC API versions.

Salesforce ReleaseLWC API Version
Summer '2358.0
Winter '2459.0

Consider these guidelines when working with LWC API versioning.

  • If you use an apiVersion that'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 60.0 and you provide 61.0, then LWC uses 60.0.
  • LWC API versioning isn't available for Aura components and LWR.
  • LWC API versioning is available only for custom components in Lightning Experience that include the *.js-meta.xml file.
  • Custom components in LWR use the latest LWC API version when not running in Lightning Experience or Experience Cloud.
  • Components on the same page or within the same managed package can have different API versions.