zephyr-codemod

zephyr-codemod

A codemod tool that automatically adds the withZephyr plugin to bundler configurations in your project.

What is Zephyr?

Zephyr is a developer-first SaaS platform focused on Module Federation for building, deploying, and managing micro-frontend applications. It provides:

• 🚀 Edge-deployed micro-frontends with global CDN distribution
• 🔧 Universal bundler support - works with Webpack, Vite, Rollup, and more
• 📊 Real-time analytics and deployment insights
• 🛡️ Version management with rollback capabilities
• 🌐 Custom domains and environment management

Learn more at zephyr-cloud.io | Documentation | GitHub

Quick Start

Get your project Zephyr-ready in seconds:

# 1. Run the codemod to add Zephyr plugins to your bundler configs
npx zephyr-codemod --install
# or: pnpm dlx zephyr-codemod --install
# or: yarn dlx zephyr-codemod --install  
# or: bunx zephyr-codemod --install

# 2. That's it! Your bundler is now configured for Zephyr deployments
# Visit https://app.zephyr-cloud.io to deploy your micro-frontends

Supported Bundlers

This codemod supports 10+ bundlers with their respective Zephyr plugins:

• Webpack (zephyr-webpack-plugin)
• Rspack (zephyr-rspack-plugin)
• Vite (vite-plugin-zephyr)
• Rollup (rollup-plugin-zephyr)
• Rolldown (zephyr-rolldown-plugin)
• Modern.js (zephyr-modernjs-plugin)
• RSPress (zephyr-rspress-plugin)
• Parcel (parcel-reporter-zephyr)
• RSBuild (zephyr-rspack-plugin)
• Re.Pack (React Native) (zephyr-repack-plugin)

Installation

No installation required! Use directly with your package manager:

# npm
npx zephyr-codemod

# pnpm  
pnpm dlx zephyr-codemod

# yarn
yarn dlx zephyr-codemod

# bun
bunx zephyr-codemod

💡 Tip: Using npx/dlx/bunx ensures you always get the latest version without cluttering your global packages.

Usage

Basic Usage

Run the codemod in your project directory:

npx zephyr-codemod

This will:

• Search for bundler configuration files in the current directory and subdirectories
• Detect which bundler each config file is for
• Add the appropriate withZephyr plugin configuration
• Add the necessary import/require statements

Command Line Options

# Show what would be changed without modifying files
npx zephyr-codemod --dry-run

# Automatically install missing plugin packages  
npx zephyr-codemod --install

# Specify a different directory
npx zephyr-codemod ./my-project

# Only process specific bundlers
npx zephyr-codemod --bundlers webpack vite

# Combine options
npx zephyr-codemod ./src --dry-run --bundlers rollup --install

# Use with other package managers
pnpm dlx zephyr-codemod --install
yarn dlx zephyr-codemod --dry-run
bunx zephyr-codemod --bundlers vite rollup

Options

• [directory] - Directory to search for config files (default: current directory)
• -d, --dry-run - Show what would be changed without modifying files
• -b, --bundlers <bundlers...> - Only process specific bundlers
• -i, --install - Automatically install missing plugin packages

Examples

Before and After

Webpack Configuration

Before:

const { composePlugins, withNx, withReact } = require('@nx/webpack');

module.exports = composePlugins(
  withNx(),
  withReact(),
  (config) => {
    return config;
  }
);

After:

const { withZephyr } = require('zephyr-webpack-plugin');
const { composePlugins, withNx, withReact } = require('@nx/webpack');

module.exports = composePlugins(
  withNx(),
  withReact(),
  withZephyr(),
  (config) => {
    return config;
  }
);

Vite Configuration

Before:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react(),
  ],
});

After:

import { withZephyr } from 'vite-plugin-zephyr';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react(),
    withZephyr(),
  ],
});

Rollup Configuration

Before:

module.exports = (config) => {
  return config;
};

After:

const { withZephyr } = require('rollup-plugin-zephyr');

module.exports = (config) => {
  config.plugins.push(withZephyr());
  return config;
};

Package Management

The codemod can automatically install missing Zephyr plugin packages using the --install flag.

Package Manager Detection

The tool automatically detects your package manager by checking for:

• Lock files (in order of priority):

  • pnpm-lock.yaml → pnpm
  • yarn.lock → yarn
  • package-lock.json → npm
  • bun.lockb → bun

• package.json packageManager field

• Monorepo indicators (pnpm-workspace.yaml, lerna.json)

• Environment variables (npm_config_user_agent)

Supported Package Managers

• npm: npm install --save-dev <package>
• yarn: yarn add --dev <package>
• pnpm: pnpm add --save-dev <package>
• bun: bun add --dev <package>

Usage with Package Installation

# Install packages and update configs in one command
npx zephyr-codemod --install

# Preview what packages would be installed
npx zephyr-codemod --dry-run --install

# The tool will show you which packages need to be installed if you don't use --install
npx zephyr-codemod
# Output: 💡 Tip: Use --install to automatically install missing packages:
#           vite-plugin-zephyr
#           zephyr-webpack-plugin

Configuration File Detection

The codemod automatically detects and processes these configuration files:

• webpack.config.js/ts/mjs
• rspack.config.js/ts/mjs
• vite.config.js/ts/mjs
• rollup.config.js/ts/mjs
• rolldown.config.js/ts/mjs
• modern.config.js/ts/mjs
• rspress.config.js/ts/mjs
• .parcelrc/.parcelrc.json

Integration Patterns

The codemod recognizes and handles various configuration patterns:

Webpack/Rspack

• composePlugins() calls (Nx style)
• plugins: [] arrays
• Direct module.exports assignments

Vite/Rolldown

• defineConfig() calls
• plugins: [] arrays

Rollup

• Function-based configs with config.plugins.push()
• plugins: [] arrays

Modern.js/RSPress

• defineConfig() calls with plugins: [] arrays

Parcel

• JSON configuration with reporters array

Safety Features

• Dry run mode: Preview changes before applying them
• Duplicate detection: Skips files that already have withZephyr configured
• Error handling: Continues processing other files if one fails
• Backup recommendation: Always commit your changes before running codemods

Troubleshooting

Common Issues

• "Could not parse file" - The configuration file has syntax errors or uses unsupported patterns
• "No suitable pattern found" - The codemod doesn't recognize the configuration structure
• "Already has withZephyr" - The plugin is already configured (this is expected behavior)

Manual Configuration

If the codemod doesn't work for your specific configuration, you can manually add the withZephyr plugin:

• Install the appropriate plugin package
• Import/require the withZephyr function
• Add it to your bundler's plugin configuration

Refer to the individual plugin documentation for specific setup instructions.

Development

Building

The codemod is written in TypeScript and bundled with tsup:

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Development mode with watch
pnpm run dev

# Type checking
pnpm run typecheck

Project Structure

src/
├── index.ts           # Main CLI entry point
├── types.ts           # TypeScript type definitions
├── bundler-configs.ts # Bundler configuration definitions
├── transformers.ts    # AST transformation functions
└── package-manager.ts # Package management utilities

Contributing

Found a configuration pattern that isn't supported? Please open an issue or submit a pull request!

License

MIT