A helper-tool that will provide metro config for KeplerCompatibility.
npm install @amazon-devices/kepler-compatibility-metro-configKepler 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.
If you find for any reason those changes are not applied (see TROUBLESHOOTING) follow steps in next section.
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
);
`
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.vpkgassume 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'.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.