npm.io
0.0.7 • Published 5 months ago

@amazon-devices/kepler-compatibility-metro-config

Licence
See license in LICENSE
Version
0.0.7
Deps
0
Size
27 kB
Vulns
0
Weekly
0

KeplerCompatibilityMetroConfig

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 Custom Metro
  1. Install the NPM library:

    "devDependencies": {
        "@amazon-devices/kepler-compatibility-metro-config": "^0.0.6",
    }
  2. 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
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: The selected library has not properly defined kepler-compatibility.json for that version.

SOLUTION: Update the NPM package of the selected library to include a valid kepler-compatibility.json(the version of the package should have corresponding value in kepler-compatibility.json). 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.

Requirements

  • Node.js >= 16.0.0
  • React Native >= 0.72.0
  • Metro >= 0.72.0