Disable Lightning Locker for an Aura Component

To disable Lightning Locker for an Aura component, set the component's API version to 39.0 or earlier. If a component is set to API version 40.0 or later, Lightning Locker is enabled. If your Aura component uses a base component that has a minimum API version later than 39.0, you can’t disable Locker on your component.

Salesforce API version 40.0 corresponds to Summer ’17, when Lightning Locker was enabled for all orgs. Lightning Locker is disabled for any component created before Summer ’17 because these components have an API version earlier than 40.0.

To disable Lightning Locker for an Aura component, in the AuraDefinitionBundle metadata of the component, set the apiVersion field to 39.0.

In this example, the metadata file myComponent.cmp-meta.xml for component myComponent.cmp sets the API version to 39.0.

If your Aura component uses a base component that has a minimum API version later than 39.0, you can’t disable Locker on your component. For example, the base component lightning:map requires API version 44.0 or later. If you use lightning:map and set apiVersion to 39.0 in myComponent.cmp-meta.xml, an error occurs. For example, if you add the component to a page in Lightning App Builder, this error message is shown.

Component API version is too old: 'markup://c:myComponent' must be set to API version '44' or later to use component 'markup://lightning:map'

For consistency and ease of debugging, we recommend that you set the same Salesforce API version for all custom components in your app, containment hierarchy (component within component), or extension hierarchy (component extending component).

If you mix API versions in your containment or extension hierarchy, and Lightning Locker is enabled for some components but disabled for other components, then your app is harder to debug.

Lightning Locker is enabled for a component or an application purely based on component API version. The extension hierarchy for a component doesn’t factor into Lightning Locker enforcement.

Let’s look at an example where a Car component extends a Vehicle component. Car has API version 39.0 so Lightning Locker is disabled. Vehicle has API version 40.0 so Lightning Locker is enabled.

Now, let’s say that Vehicle adds an expando property, _counter, to the window object by assigning a value to window._counter. Because Lightning Locker is enabled for Vehicle, the _counter property is added to SecureWindow, which is the secure wrapper for window for the component’s namespace. The property isn’t added to the native window object.

Lightning Locker is disabled for Car, so the component has access to the native window object. Car can’t see the _counter property as it’s only available in the SecureWindow object.

The containment hierarchy within an application or a component doesn’t factor into Lightning Locker enforcement.

Let’s look at an example where a Bicycle component contains a Wheel component. If Bicycle has API version 40.0, Lightning Locker is enabled. If Wheel has API version 39.0, Lightning Locker is disabled for Wheel even though it’s contained in a component, Bicycle, that has Lightning Locker enabled.

See Also

• Select the Locker API Version for an Org
• Secure Wrappers
• Sharing JavaScript Code Across Components
• Lightning Aura Components Developer Guide: Aura Component Versioning for Managed Packages
• Lightning Aura Components Developer Guide: Base Components with Minimum API Version Requirements