Zephyr Bundler Configuration Codemod

1.0.2 · active · verified Tue Apr 21

The `with-zephyr` package provides a codemod utility designed to automatically inject the `withZephyr` plugin into various JavaScript bundler configurations. This tool is essential for projects integrating with the Zephyr Cloud platform, facilitating features like Module Federation, Over-The-Air (OTA) updates, and streamlined deployments for micro-frontends. It supports a wide array of bundlers, including Webpack, Vite, Rollup, Rspack, and others within ecosystems like Astro and Modern. Currently at version 1.0.2, the package maintains an active development pace with frequent patch releases, often addressing security vulnerabilities and improving compatibility. Its primary differentiator is its role as an automated transformation tool, simplifying the integration of Zephyr-specific plugins into complex build setups without manual configuration edits. This package is distinct from the Zephyr Real-Time Operating System (RTOS).

Common errors

```
Error: Failed to parse configuration file: Unexpected token ','
```
cause An older version of `with-zephyr` (prior to v0.1.16) encountered a trailing comma in a JavaScript/TypeScript array within a bundler configuration file, which it couldn't correctly handle.

fix Upgrade `with-zephyr` to `^0.1.16` or higher (`npm install with-zephyr@latest`). If the issue persists with an older version for specific reasons, manually remove any trailing commas from plugin arrays in your bundler configuration files.
```
Command failed: npx with-zephyr init
Error: No supported bundler configuration found.
```
cause The codemod could not detect a supported bundler configuration file (e.g., `webpack.config.js`, `vite.config.ts`) in the current directory or its common subdirectories, or an unexpected file structure prevented automated modification.

fix Ensure you are running the command in the root of a project with a standard bundler configuration. Verify that your bundler configuration file follows common patterns. Consult Zephyr Cloud documentation for supported bundler versions and manual integration steps if the codemod fails to detect your setup.

Warnings

breaking The v1.0.0 release marked a major version bump. While specific user-facing breaking API changes for the `with-zephyr` codemod were not explicitly detailed in the changelog, it indicated significant internal restructuring and a move to a stable release state. Users migrating from pre-1.0.0 versions should test thoroughly.
Fix: Refer to the GitHub changelog for `zephyr-packages` and consult Zephyr Cloud documentation for any new migration guides related to bundler configurations or plugin usage. Thoroughly test existing build pipelines.
gotcha Recent patch releases (e.g., v1.0.2, v1.0.1) included fixes for high and critical pnpm audit vulnerabilities. Older versions may contain known security issues.
Fix: Upgrade to the latest stable version of `with-zephyr` immediately to benefit from security remediations: `npm install with-zephyr@latest` or `pnpm update with-zephyr`.
gotcha Versions prior to v0.1.16 had issues handling trailing commas within plugin arrays in bundler configurations, potentially leading to parsing errors or incorrect modifications.
Fix: Ensure your project's bundler configuration files are updated to a version of `with-zephyr` greater than or equal to `0.1.16` to correctly parse and modify plugin arrays. If using an older version, manually remove any trailing commas from plugin arrays in your bundler configuration files or upgrade.

Install

npm install with-zephyr npm
yarn add with-zephyr yarn
pnpm add with-zephyr pnpm

Imports

runCodemod
wrong:
```
const { runCodemod } = require('with-zephyr');
```
correct:
```
import { runCodemod } from 'with-zephyr';
```
Primarily an ESM-first utility; programmatic API for custom automation scripts. The main usage is via CLI.
applyCodemod
wrong:
```
import applyCodemod from 'with-zephyr';
```
correct:
```
import { applyCodemod } from 'with-zephyr';
```
Named export for applying the codemod logic directly, typically used in build scripts or CI/CD pipelines.

Quickstart

Demonstrates how to invoke the `with-zephyr` codemod via the command line to initialize Zephyr plugin integration.

npx with-zephyr --help
# Example: Run the codemod to automatically configure a project
npx with-zephyr init
# The 'init' command would typically detect your bundler configuration
# (e.g., webpack.config.js, vite.config.ts) and apply the necessary
# modifications to include the Zephyr plugin for Module Federation and deployment.
# Always review changes made by codemods before committing.

view raw JSON →