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

$3

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.

$3

1. Update Config:
``
test-dependencies = {
2.x_vodka = {
KeplerCompatibilityMetroConfig = 1.0;
};
};
`

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

$3

`
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'.

$3

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.