Version Lightning Web Components

Version your Lightning web components to ensure that your components aren’t affected when Salesforce ships new features, bug fixes, and performance improvements that change existing behavior. Update the API version for your components to use new features and improvements. Versioning also helps Salesforce deprecate legacy features when necessary.

AVAILABLE API VERSIONS
Available in LWC API v59.0 and later
Required in Spring ’25 (API v63.0) and later

LWC began support for versioning custom components in Winter '24. Beginning in Spring ’25, versioning custom components is required, even if your component uses an older API version.

Components that were previously saved without setting an API version continue to run as before. However, the next time you modify the component, you'll need to set the API version, too. Attempting to save an unversioned component to Salesforce results in an error.

To aid transitioning unversioned components to versioned, Salesforce adds an apiVersion tag to unversioned components when you retrieve them from Salesforce. The API version added is the same the component already uses. This ensures that the component's behavior won't change when you save it with the new apiVersion tag.

A component sets a version so that it can depend on a specific version of Salesforce. The API version you set for a component tells the LWC framework to behave as it did for the Salesforce release corresponding to the specified API version for that component. This ensures a stable execution environment for your components.

A component is set to only one API version. That is, every HTML, CSS, and JavaScript file of a component uses the same API version.

LWC allows composition of components that use different API versions. You can use components with different API versions on the same page. You can also use a component with one API version inside of, or to contain, a component with a different API version.

It's a best practice to update the API version of your components whenever you modify them, so that they take advantage of the latest features and bug fixes.

To specify a component's API version, set the apiVersion key in the .js-meta.xml file for the component.

apiVersion values are validated when you save a component to Salesforce. Vaidation errors prevent your component from being saved to Salesforce.

  • The earliest valid API version is 45.0, which corresponds to Summer ’23.
  • The earliest practical API version is 58.0. API versions 58.0 and earlier all correspond to Summer ’23.
  • API version 59.0 was the first to introduce versioning for custom components. This corresponds to Winter ’24.
  • The latest valid API version is the current release of Salesforce.

Setting an API version outside this range or using a non-standard format for the apiVersion value can result in a warning or error when you save the component to Salesforce.

Regardless of apiVersion, custom components always use the latest version of Lightning Data Service and base Lightning components.

See Also