{"id":15945,"library":"zephyr-metro-plugin","title":"Zephyr Metro Plugin","description":"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.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/ZephyrCloudIO/zephyr-packages","tags":["javascript","metro","react-native","zephyr","zephyr-cloud","module-federation","ota","over-the-air","deployment","typescript"],"install":[{"cmd":"npm install zephyr-metro-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add zephyr-metro-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add zephyr-metro-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core bundler dependency for React Native applications.","package":"metro","optional":false},{"reason":"Framework for building native mobile applications.","package":"react-native","optional":false},{"reason":"Internal Zephyr Cloud integration and utilities.","package":"zephyr-xpack-internal","optional":false}],"imports":[{"note":"The primary export is a function that wraps your Metro configuration. Use ESM import syntax for modern React Native setups, especially with TypeScript.","wrong":"const withZephyr = require('zephyr-metro-plugin');","symbol":"withZephyr","correct":"import withZephyr from 'zephyr-metro-plugin';"},{"note":"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`.","symbol":"MetroConfig","correct":"import type { MetroConfig } from 'metro-config';"},{"note":"For TypeScript users, import this type to define the options object passed to `withZephyr` for enhanced type checking.","symbol":"ZephyrPluginOptions","correct":"import type { ZephyrPluginOptions } from 'zephyr-metro-plugin';"}],"quickstart":{"code":"import { getDefaultConfig } from 'expo/metro-config'; // Or 'metro-config' if not using Expo\nimport withZephyr from 'zephyr-metro-plugin';\nimport path from 'path';\n\nconst projectRoot = __dirname;\nconst config = getDefaultConfig(projectRoot);\n\n// Ensure required environment variables are set for Zephyr Cloud\nconst zephyrAppId = process.env.ZEPHYR_APP_ID ?? '';\nconst zephyrApiKey = process.env.ZEPHYR_API_KEY ?? '';\n\nif (!zephyrAppId || !zephyrApiKey) {\n  console.warn('ZEPHYR_APP_ID and ZEPHYR_API_KEY environment variables are required for Zephyr Cloud integration.');\n}\n\nmodule.exports = withZephyr(config, {\n  zephyrAppId: zephyrAppId,\n  zephyrApiKey: zephyrApiKey,\n  // Optional: Define custom Zephyr options\n  // moduleFederation: {\n  //   shared: ['react', 'react-native'],\n  // },\n  // ota: {\n  //   enabled: true,\n  //   channel: 'production',\n  // },\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"The package is not installed, or there's a typo in the import path.","error":"Error: Cannot find module 'zephyr-metro-plugin' or its corresponding type declarations."},{"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.","cause":"Incorrect import syntax for CommonJS or a mistaken named import when the package provides a default export.","error":"ReferenceError: withZephyr is not defined"},{"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.","cause":"The `zephyrApiKey` option passed to `withZephyr` is empty or incorrect, preventing authentication with Zephyr Cloud.","error":"Metro has encountered an error: Zephyr Cloud API Key is missing or invalid."}],"ecosystem":"npm"}