KeplerCompatibilityMetroConfig (Internal README -- Un-published in .tgz)

Kepler Compatibility Metro Config (KC Metro) is a standalone NPM package that provides a metro plugin for Applications that assists in making the system-bundled libraries available to that application at runtime.

Installation

Applications built with KCLI

Apps that are set up with the latest Kepler CLI flow (e.g: https://developer.amazon.com/docs/kepler/cli-tools.html) do not need to make updates to your application, in most cases.

If you find for any reason those changes are not applied (see TROUBLESHOOTING) follow steps in next section.

Applications built with KUBT / Custom Metro

1. Update Config:

   test-dependencies = {
       2.x_vodka = {
           KeplerCompatibilityMetroConfig = 1.0;
       };
   };

2. Install the NPM library:

"devDependencies": { "@amazon-devices/kepler-compatibility-metro-config": "^0", } ```

1. Import and include the plugin in metro.config.js. It is recommended that getKeplerCompatibilityMetroConfig be applied near the end, prior to app-defined config, as seen in this example:

const {getKeplerCompatibilityMetroConfig} = require('@amazon-devices/kepler-compatibility-metro-config');

...

mergeConfig( getDefaultConfig(__dirname), getKeplerCompatibilityMetroConfig(), # ADD config ); ```

TESTING

If your application has applied the metro.config.js appropriately, you will find global.KEPLER_MODULE_MAP has been defined.

The following is an example only, your map may have more/less determinant on the dependencies of your Application:

global.KEPLER_MODULE_MAP = {"@amazon-devices/kepler-compatibility":{"0.0.1":"/com.amazon.kepler.experimental.features_2025_02@IFeature"},"@amazon-devices/react-native-gesture-handler":{"2.0.0":"/com.amazon.kepler.gesture_handler_2@IGestureHandler_0"},"@amazon-devices/react-native-kepler":{"2.0.0":"/com.amazon.kepler.keplerscript_2@IKeplerScript_0"},"@amazon-devices/react-native-reanimated":{"2.0.0":"/com.amazon.kepler.reanimated_2@IReanimated_0"}};

To validate your metro configuration at build-time, you can use this script:

# First, move your mergeConfig to a variable
const finalConfig = mergeConfig(getDefaultConfig(__dirname), getKeplerCompatibilityMetroConfig(), config);

# getPolyfills is a list of files, we need to read
# the file to print its content:
function printFile(path) {
  const fs = require('fs');
  const file = fs.readFileSync(path, 'utf8');
  return file;
}

# This will print
if (finalConfig.serializer) {
    console.log('\n\n[metro_config_debug] Metro Config Validation -- Serializer configuration:');
    Object.keys(finalConfig.serializer).forEach(key => {
        // Print the sesrializer getPolyfills (Typically, there is more than one.)
        if (typeof finalConfig.serializer[key] === 'function' && key === 'getPolyfills') {
            console.log(`[metro_config_debug] ${key}: [Function ${finalConfig.serializer[key].name}]`);
            const result = finalConfig.serializer[key]();
            console.log('[metro_config_debug] Result:', result);
            console.log('[metro_config_debug] Output of file in result is:');
            result.forEach((res, idx) => console.log(`[metro_config_debug] #${idx}:\n---\n${printFile(res)}\n---\n`));
        }
    });
}

# Dont forget to export the variable
module.exports = finalConfig;

TROUBLESHOOTING

Problem Behavior: My Application is using KeplerCompatibility and MetroConfig, but when I expected the isPresentOnOS, isAppTargeting APIs I got a false value when I expeected true.

Step 1: Validate your App has the proper needs.module declared

dev vpt unpack /path/to/latest.vpkg

# assume App Name is `example-app.vpkg`, folder extracted is `example-app`. 

# open manifest.toml

If needs.module have been defined, then KeplerCompatibility and KeplerModuleManifestBuilder have created the appropriate modules in the vpkg. The issue might lie in this package.

PROBLEM: If your specific library is not present as a [[needs.module]] then your NPM .tgz has not exported a valid kepler-compatibility.json. SOLUTION: Update your NPM package to include a valid kepler-compatibility.json, all versions should have a valid module id as defined in the kepler-system-conf.toml. The kepler-compatibility.json must be included in 'files'.

Step 2: Debug app and validate the globals were included at runtime

Use the script provided to ensure the values exist at build time. Use standard JS debugging tools to validate that those globals exist at the time your app is running and makes the check.