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

> A helper-tool that will provide metro config for KeplerCompatibility.

Latest version **0.0.7** (published 2026-06-17) · See license in LICENSE license · 0 weekly downloads

## Install

```sh
npm install @amazon-devices/kepler-compatibility-metro-config
pnpm add @amazon-devices/kepler-compatibility-metro-config
yarn add @amazon-devices/kepler-compatibility-metro-config
bun add @amazon-devices/kepler-compatibility-metro-config
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.7 |
| Published | 2026-06-17 |
| First published | 2025-09-25 |
| Weekly downloads | 0 |
| License | See license in LICENSE |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 27.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | amazon-devices-admin |

## Links

- npm: https://www.npmjs.com/package/@amazon-devices/kepler-compatibility-metro-config
- npm.io page: https://npm.io/package/@amazon-devices/kepler-compatibility-metro-config

## Recent versions

- 0.0.7 (latest) — 2026-06-17
- 0.0.6 — 2025-09-25

## README

# 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

---
_Source: https://npm.io/package/@amazon-devices/kepler-compatibility-metro-config · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
