Zephyr Vite Plugin

1.0.2 verified Mon Apr 27 auth: no javascript

Vite plugin (v1.0.2) for integrating Zephyr Cloud's module federation and deployment platform into Vite-based projects. Enables seamless federated module loading, deployment to Zephyr Cloud, and version management. Requires Vite ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0, Rollup ^4.0.0, and @module-federation/vite ^1.13.2. Ships TypeScript types. Key differentiators: purpose-built for Zephyr Cloud with no-config setup and automatic module synchronization. Release cadence: patch releases every few weeks with occasional major bumps.

Common errors

error Cannot find module 'vite-plugin-zephyr' ↓

cause CJS require() used instead of ESM import.

fix

Change to import zephyr from 'vite-plugin-zephyr' and ensure package.json has "type": "module".

error ERR_PNPM_RECURSIVE_RUN ERR vite-plugin-zephyr is not a valid plugin option. Expected a function, got an object. ↓

cause Using the default export incorrectly without calling it as a function.

fix

Use zephyr() instead of zephyr in the plugins array.

error Module federation build failed: @module-federation/vite version mismatch ↓

cause Incompatible version of @module-federation/vite installed.

fix

Run npm install @module-federation/vite@^1.13.2 to install the correct peer dependency.

Warnings

deprecated The 'withZephyr' helper has been deprecated in v1.0.0. Use the default import directly. ↓

fix Replace `import { withZephyr } from 'vite-plugin-zephyr'` with `import zephyr from 'vite-plugin-zephyr'`.

gotcha Plugin must be placed AFTER the Vue or React plugin in the plugins array to ensure correct processing. ↓

fix Order plugins correctly: `plugins: [vue(), react(), zephyr()]`.

breaking v1.0.0 changed the default export from an object to a function. Direct plugin registration without calling the function will fail. ↓

fix Use `zephyr()` as a function call, not `new zephyr()` or just `zephyr`.

gotcha The plugin requires @module-federation/vite version ^1.13.2. Older or newer major versions may cause incompatibility. ↓

fix Install compatible version: `npm install @module-federation/vite@^1.13.2`.

Install

npm install vite-plugin-zephyr

yarn add vite-plugin-zephyr

pnpm add vite-plugin-zephyr

Imports

default (plugin)

wrong

const zephyr = require('vite-plugin-zephyr')

correct

import zephyr from 'vite-plugin-zephyr'

ESM-only; CJS require() will fail. Use import syntax.

ZephyrPluginOptions

import type { ZephyrPluginOptions } from 'vite-plugin-zephyr'

TypeScript only; no runtime value.

withZephyr

wrong

import withZephyr from 'vite-plugin-zephyr/withZephyr'

correct

import { withZephyr } from 'vite-plugin-zephyr'

Exported as named export from the main package, not a subpath.

Quickstart

Basic Vite config with Zephyr plugin enabling module federation and deployment integration.

import { defineConfig } from 'vite';
import zephyr from 'vite-plugin-zephyr';

export default defineConfig({
  plugins: [
    zephyr({
      // Optional: specify Zephyr project URL or API key
      projectUrl: process.env.ZEPHYR_PROJECT_URL ?? '',
      apiKey: process.env.ZEPHYR_API_KEY ?? '',
      // Enable hot reload for federated modules
      hotReload: true
    })
  ]
});