Don’t Mix Component API Versions

For consistency and ease of debugging, we recommend that you set the same 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 LockerService is enabled for some components and disabled for other components, your app will be harder to debug.

Extension Hierarchy

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

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

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

LockerService 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.

This subtle behavior can cause much gnashing of teeth when your code doesn’t work as you expect. You’ll never get that debugging time back! Save yourself some grief and use the same API version for all components in an extension hierarchy.

Containment Hierarchy

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

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

Due to the mix of component API versions, you’re likely to run into issues similar to those for the extension hierarchy. We recommend that you set the same API version for all components in your app or component hierarchy, when possible.