Zephyr Metro Plugin

1.0.2 · active · verified Tue Apr 21

zephyr-metro-plugin is a Metro bundler plugin designed to integrate React Native applications with Zephyr Cloud for advanced deployment features. It enables Over-the-Air (OTA) updates, supports Module Federation for dynamic code loading, and streamlines the overall deployment process for iOS and Android applications. Currently stable at version 1.0.2, the package maintains an active development status with a consistent release cadence, featuring frequent patch updates that address dependency management and minor bug fixes. It serves as a critical bridge for React Native developers aiming to leverage Zephyr Cloud's capabilities, distinguishing itself by offering comprehensive deployment and update management directly within the Metro bundling workflow, which is particularly beneficial for large-scale or continuously evolving mobile applications.

Common errors

```
Error: Cannot find module 'zephyr-metro-plugin' or its corresponding type declarations.
```
cause The package is not installed, or there's a typo in the import path.

fix Run `npm install zephyr-metro-plugin` or `yarn add zephyr-metro-plugin`. Double-check the import statement in your `metro.config.ts` or `metro.config.js`.
```
ReferenceError: withZephyr is not defined
```
cause Incorrect import syntax for CommonJS or a mistaken named import when the package provides a default export.

fix For CommonJS, use `const withZephyr = require('zephyr-metro-plugin').default;` if using a transpiled ESM default export, or ensure you are using `import withZephyr from 'zephyr-metro-plugin';` in an ESM context.
```
Metro has encountered an error: Zephyr Cloud API Key is missing or invalid.
```
cause The `zephyrApiKey` option passed to `withZephyr` is empty or incorrect, preventing authentication with Zephyr Cloud.

fix Verify that your `ZEPHYR_API_KEY` environment variable is correctly set and accessible to your Metro configuration. Ensure there are no leading/trailing spaces or typos.

Warnings

breaking The release of v1.0.0, following earlier 0.x versions, indicates potential breaking API changes and configuration adjustments from prior minor releases. While specific breaking changes are not detailed in the provided changelog, a major version bump inherently implies non-backward compatible modifications.
Fix: Review the official migration guide or latest documentation for `zephyr-metro-plugin` when upgrading from any 0.x version to 1.x. Test your application thoroughly after upgrading and adjust your `metro.config.ts`/`.js` and Zephyr Cloud related configurations as needed.
gotcha Several patch versions (e.g., v1.0.2, v1.0.1, v0.2.0) included fixes for 'high and critical pnpm audit vulnerabilities' and 'security vulnerabilities'. Running older versions might expose your project to known security risks.
Fix: Always ensure you are using the latest stable version of `zephyr-metro-plugin` to benefit from the most recent security remediations. Regularly update your project's dependencies and run security audits.
gotcha The plugin relies on `ZEPHYR_APP_ID` and `ZEPHYR_API_KEY` environment variables. Failure to set these correctly will prevent the plugin from functioning as expected or connecting to Zephyr Cloud.
Fix: Ensure `ZEPHYR_APP_ID` and `ZEPHYR_API_KEY` are properly configured in your build environment (e.g., `.env` file, CI/CD pipeline variables). The `quickstart` code provides a warning if these are missing.

Install

npm install zephyr-metro-plugin npm
yarn add zephyr-metro-plugin yarn
pnpm add zephyr-metro-plugin pnpm

Imports

withZephyr
wrong:
```
const withZephyr = require('zephyr-metro-plugin');
```
correct:
```
import withZephyr from 'zephyr-metro-plugin';
```
The primary export is a function that wraps your Metro configuration. Use ESM import syntax for modern React Native setups, especially with TypeScript.
MetroConfig
```
import type { MetroConfig } from 'metro-config';
```
While 'MetroConfig' is not exported by this plugin, it's a crucial type from 'metro-config' often used when defining your Metro configuration with TypeScript for better type safety, especially when passing it to `withZephyr`.
ZephyrPluginOptions
```
import type { ZephyrPluginOptions } from 'zephyr-metro-plugin';
```
For TypeScript users, import this type to define the options object passed to `withZephyr` for enhanced type checking.

Quickstart

This quickstart demonstrates how to integrate `zephyr-metro-plugin` into your `metro.config.ts` or `metro.config.js` file, enabling Zephyr Cloud features. It wraps your existing Metro configuration with `withZephyr` and requires environment variables for authentication.

import { getDefaultConfig } from 'expo/metro-config'; // Or 'metro-config' if not using Expo
import withZephyr from 'zephyr-metro-plugin';
import path from 'path';

const projectRoot = __dirname;
const config = getDefaultConfig(projectRoot);

// Ensure required environment variables are set for Zephyr Cloud
const zephyrAppId = process.env.ZEPHYR_APP_ID ?? '';
const zephyrApiKey = process.env.ZEPHYR_API_KEY ?? '';

if (!zephyrAppId || !zephyrApiKey) {
  console.warn('ZEPHYR_APP_ID and ZEPHYR_API_KEY environment variables are required for Zephyr Cloud integration.');
}

module.exports = withZephyr(config, {
  zephyrAppId: zephyrAppId,
  zephyrApiKey: zephyrApiKey,
  // Optional: Define custom Zephyr options
  // moduleFederation: {
  //   shared: ['react', 'react-native'],
  // },
  // ota: {
  //   enabled: true,
  //   channel: 'production',
  // },
});

view raw JSON →