Enable Backward Compatibility

When you first release your app, backward compatibility is not a concern. However, when you update your app to use newer versions of @amazon-devices/ system distributed libraries and resubmit to the Amazon Appstore, the devices that still contain older versions of these libraries won't be able to install or update to your latest app version.

React Native for Vega provides an opt-in backward compatibility feature that allows your app to support both older and newer versions of these libraries simultaneously. This feature is crucial for maintaining a wide user base and providing a consistent experience across different system versions.

About system distributed libraries

System distributed libraries are JavaScript packages, always prefixed with @amazon-devices/, that are pre-installed on the device to optimize app size and loading time.

As it relates to backward compatibility, the version of each of these libraries is static until the device receives a new flash or OTA update.

When a new version of a system distributed library is released (for example, 2.1.0), React Native for Vega maintains compatibility with previous versions (like 2.0.0) within the same major version.

Opting in and opting out

When updating your app, you have the choice to opt-in or opt-out of backward compatibility.

Opting out means your app will only support the latest version of system distributed libraries, which can simplify development and testing. However, opting out also means your app will not be installable on devices running older versions of these libraries.

Opting in to backward compatibility requires additional code and configuration changes but offers significant benefits:

• Wider device support - Your app can run on devices with older system versions.
• Access to new features - Use new library features while maintaining support for older versions.
• Single app submission - Deploy once to support multiple system versions.
• Automatic verification - System validates compatibility before installation.

There are valid reasons to opt out of backward compatibility, such as during a major version update where breaking changes are introduced. For most use cases, backward compatibility is recommended to maximize your app's reach.

Configuring backward compatibility support

Install compatibility library

Run the following command to install the library:

npm install @amazon-devices/kepler-compatibility

Define compatibility requirements

To specify backward compatibility for a library used in your app, you'll need to add the name of the library and its needs and wants to the backwardCompatibility to your kepler block in package.json. You should also add the compatibility library to your dependencies section.

  {
    "name": "MyApp",
    "version": "1.0.0",
    "dependencies": {
      "@amazon-devices/kepler-compatibility": "^0",
      "@amazon-devices/react-native-gesture-handler": "2.4.0"
    },
    "kepler": {
      "backwardCompatibility": {
        "@amazon-devices/react-native-gesture-handler": {
          "needs": "2.0.0", // Minimum supported
          "wants": "<=2.4.0" // Maximum supported
        }
      },
      ...
    }
  }

• needs - The lowest version that can be used by your app. The value must be an exact semver version. that must be present for your app to run. If these modules are not available on a device, your app cannot be installed.

• wants - The maximum version that can be used by your app. The value should be set to a semver range that is inclusive of the needs. For example, valid wants for the range above would be: (<2.5.0, <=2.2.0 and ^2.0.0). Set this value to the highest value you verified to work at time of submission.

Add version checks in code

The isPresentOnOS API helps you verify at runtime whether the required library version is installed on the system, which is especially important when your code depends on specific older versions or needs features that are only available in newer versions.

import { isPresentOnOS } from '@amazon-devices/kepler-compatibility';
import * as GestureHandler from '@amazon-devices/react-native-gesture-handler';

// In this example, this new feature was introduced in 2.2.0
const supportsNewGesture = useMemo(
  () => isPresentOnOS("@amazon-devices/react-native-gesture-handler", "2.2.0"),
  []
);

function MyComponent() {
  // Check if newer version is available before using new-released features
  if (supportsNewGesture) {
    // Use new 2.2.0 features
    return <GestureHandler.NewFeature />;
  } else {
    // Fallback for devices without 2.2.0
    return <GestureHandler.LegacyFeature />;
  }
}

Testing and verification

Before submitting your app, it's important to thoroughly test on devices with both older and newer versions of the system distributed libraries you've specified in your backwardCompatibility block.

Steps to Test

1. Use Vega to install different simulators: use the CLI to install device simulators on older and newer versions, which will help simulate different real-world scenarios of pre-installed system distributed libraries.
2. Install the app.
3. Verify that the app works as expected, paying special attention to any version checks and fallback implementations for older versions, to ensure they are functioning correctly.

Example

Add support for a new feature

The example below shows you how to add support for an imagined withNewBehaviors attribute in DragGesture of @amazon-devices/react-native-gesture-handler. This allows you to switch from the legacy PanGesture implementation, but keep the previous implementation to maintain backward compatibility older library versions.

  import { isAppTargeting } from '@amazon-devices/react-native-kepler';
  import * as GestureHandler from '@amazon-devices/react-native-gesture-handler';

  function DraggableItem() {
    if (isAppTargeting("@amazon-devices/react-native-gesture-handler", "2.1.0")) {
      // New implementation using 2.1.0 features
      return (
        <GestureHandler.DragGesture
          withNewBehaviors={true}
          onDragStart={handleDragStart}
        >
          <Item />
        </GestureHandler.DragGesture>
      );
    }

    // Fallback implementation for 2.0.0
    return (
      <GestureHandler.PanGesture
        onGestureEvent={handleLegacyDrag}
      >
        <Item />
      </GestureHandler.PanGesture>
    );
  }

Troubleshooting

Common issues

A list of common problems and their solutions can be found below.

Version mismatch

• Problem - The app fails to install on some devices.
• Solution - Verify your needs version isn't higher than what's available on target devices.

Runtime errors

• Problem - Features crash on certain devices.
• Solution - Ensure you wrap all new feature usage in version checks.

Testing issues

• Problem - It's difficult to test across versions.
• Solution - Use the device simulator to test with different system versions.

Performance best practices with version check

1. Always check versions as early as possible in your component lifecycle.
2. Cache version check results to avoid repeated checks.
3. Consider creating utility functions for commonly checked feature sets, as shown in this example below.

  // Utility function example
  const featureSupport = {
    hasGestures2_1: null as boolean | null,
  };

  export function getGestureHandlerFeatures() {
    if (featureSupport.hasGestures2_1 === null) {
      featureSupport.hasGestures2_1 = isAppTargeting(
        "@amazon-devices/react-native-gesture-handler",
        "2.1.0"
      );
    }

    return {
      // Return an object of supported features based on version
      supportsHoverGesture: featureSupport.hasGestures2_1,
      supportsPinchToZoom: featureSupport.hasGestures2_1,
      // Add other feature flags as needed
    };
  }

  // Usage in a Component in App
  function MyGestureComponent() {
    const features = getGestureHandlerFeatures();
    
    if (features.supportsHoverGesture) {
      return <HoverEnabledComponent />;
    }
    return <StandardComponent />;
  }

Last updated: Oct 30, 2025