Zephyr Packages

https://github.com/zephyrcloudio/zephyr-packages
Admin
A collection of plugins and utility packages for integrating and deploying applications with the...
Tokens:14,356
Snippets:122
Trust Score:6.8
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Project Setup and Development Commands

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/create-zephyr-apps/README.md

Basic commands to navigate into the newly created project directory, install dependencies, start the development server, and build the project for production.

```bash
cd my-app

npm install

npm run dev

npm run build
```

--------------------------------

### Git Setup and Build Commands (Bash)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-agent/README.md

Provides examples of recommended Git repository setup for Zephyr deployments and demonstrates how to trigger a build. It also illustrates the automatic fallback naming convention when Git is not properly configured.

```bash
# Recommended: Proper Git setup
git init
git remote add origin git@github.com:YOUR_ORG/YOUR_REPO.git
git add . && git commit -m "Initial commit"
npm run build  # Works perfectly with full Git context

# Automatic fallback (works seamlessly)
# No git repository - uses package.json naming
npm run build  # Automatically determines naming from package.json
```

--------------------------------

### Zephyr Engine Initialization (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/docs/CONTRIBUTING.md

Demonstrates the initial step of starting the zephyr-engine, which handles authentication and environment setup for plugin development. Assumes necessary imports and context.

```typescript
// Start zephyr-engine (it will handle the authentication and start intial build environment understanding)
```

--------------------------------

### Zephyr Plugin Setup with Options in Rsbuild

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rsbuild-plugin/README.md

Shows how to configure the Zephyr plugin with options in Rsbuild. This example sets the `wait_for_index_html` option to `true`.

```javascript
// rsbuild.config.js
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { withZephyr } from 'zephyr-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReact(),
    withZephyr({
      wait_for_index_html: true, // Wait for HTML processing
    }),
  ],
});
```

--------------------------------

### Install create-zephyr-apps CLI

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/create-zephyr-apps/README.md

This section provides commands to install the create-zephyr-apps CLI tool globally or use it directly via npx. It covers installation for npm, npx, yarn, pnpm, and bun.

```bash
# npm (global)
npm install -g create-zephyr-apps

# npx (recommended)
npx create-zephyr-apps@latest

# yarn
yarn create zephyr-apps

# pnpm
pnpm create zephyr-apps

# bun
bunx create zephyr-apps
```

--------------------------------

### Install Zephyr Rspress Plugin

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rspress-plugin/README.md

Instructions for installing the zephyr-rspress-plugin using various package managers. Ensure you have Node.js 18 or higher and Rspress 0.7 or higher installed.

```bash
# npm
npm install --save-dev zephyr-rspress-plugin

# yarn
yarn add --dev zephyr-rspress-plugin

# pnpm
pnpm add --dev zephyr-rspress-plugin

# bun
bun add --dev zephyr-rspress-plugin
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/README.md

Installs all project dependencies using the pnpm package manager. This is a prerequisite for running any of the provided scripts.

```shell
pnpm install
```

--------------------------------

### Run create-zephyr-apps CLI with direct options

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/create-zephyr-apps/README.md

Example of using the create-zephyr-apps CLI to directly specify the project name and template, such as 'my-app' with the 'vite-react-ts' template.

```bash
npx create-zephyr-apps@latest my-app --template vite-react-ts
```

--------------------------------

### Install Zephyr Packages with Codemod

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/with-zephyr/README.md

Illustrates the command-line usage of the `with-zephyr` codemod to automatically install missing Zephyr plugin packages. The `--install` flag handles the installation process.

```bash
# Install packages and update configs in one command
npx with-zephyr --install

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

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

--------------------------------

### Development Server with pnpm

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/README.md

Starts the development server for local development and testing. This command is typically used during the development phase to see changes in real-time.

```shell
pnpm dev
```

--------------------------------

### Install Zephyr Rspack Plugin

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rspack-plugin/README.md

Commands to install the zephyr-rspack-plugin using different package managers like npm, yarn, pnpm, and bun. Ensure you have Node.js 18 or higher and Rspack 0.3 or higher installed.

```bash
# npm
npm install --save-dev zephyr-rspack-plugin

# yarn
yarn add --dev zephyr-rspack-plugin

# pnpm
pnpm add --save-dev zephyr-rspack-plugin

# bun
bun add --dev zephyr-rspack-plugin
```

--------------------------------

### Package.json Build Scripts for Rolldown

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rolldown-plugin/README.md

Example `scripts` section for a `package.json` file, defining common build commands for Rolldown projects, including development, production, and watch modes.

```json
{
  "scripts": {
    "dev": "rolldown --watch",
    "build": "rolldown",
    "build:prod": "NODE_ENV=production rolldown"
  }
}
```

--------------------------------

### Zephyr Plugin Setup in Rsbuild with TypeScript

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rsbuild-plugin/README.md

Illustrates the basic setup of the Zephyr plugin within an Rsbuild configuration file using TypeScript (rsbuild.config.ts).

```typescript
// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { withZephyr } from 'zephyr-rsbuild-plugin';

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

--------------------------------

### Example Plugin Directory Structure (Shell)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/docs/CONTRIBUTING.md

Provides a standard directory structure for creating a new Zephyr plugin package. This includes essential configuration files and source directories.

```shell
libs/zephyr-[bundler]-plugin/
  ├── LICENSE
  ├── README.md
  ├── jest.config.ts
  ├── package.json
  ├── project.json
  ├── src/
  │   ├── index.ts
  │   └── lib/
  ├── tsconfig.json
  ├── tsconfig.lib.json
  └── tsconfig.spec.json
```

--------------------------------

### Basic Zephyr Plugin Setup in Rsbuild

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rsbuild-plugin/README.md

Demonstrates how to add the Zephyr plugin to the Rsbuild configuration file (rsbuild.config.js). It imports necessary functions and includes `withZephyr()` in the plugins array.

```javascript
// rsbuild.config.js
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { withZephyr } from 'zephyr-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReact(),
    withZephyr(), // Add Zephyr plugin
  ],
});
```

--------------------------------

### Install Zephyr Rsbuild Plugin

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rsbuild-plugin/README.md

Installs the zephyr-rsbuild-plugin package as a development dependency using various package managers (npm, yarn, pnpm, bun).

```bash
# npm
npm install --save-dev zephyr-rsbuild-plugin

# yarn
yarn add --dev zephyr-rsbuild-plugin

# pnpm
pnpm add --save-dev zephyr-rsbuild-plugin

# bun
bun add --dev zephyr-rsbuild-plugin
```

--------------------------------

### Install Zephyr Rolldown Plugin with Package Managers

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rolldown-plugin/README.md

Instructions for installing the zephyr-rolldown-plugin using various package managers like npm, yarn, pnpm, and bun. This is a development dependency.

```bash
# npm
npm install --save-dev zephyr-rolldown-plugin

# yarn
yarn add --dev zephyr-rolldown-plugin

# pnpm
pnpm add --dev zephyr-rolldown-plugin

# bun
bun add --dev zephyr-rolldown-plugin
```

--------------------------------

### Configure Zephyr Plugin with Nx and Rspack

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rspack-plugin/README.md

Example configuration for Rspack projects managed by Nx. This demonstrates how to compose Rspack plugins, including `@nx/rspack/module-federation` and `zephyr-rspack-plugin`, to enable Module Federation and Zephyr deployment.

```javascript
// rspack.config.js
import { composePlugins, withNx } from '@nx/rspack';
import { withReact } from '@nx/react';
import { withModuleFederation } from '@nx/rspack/module-federation';
import { withZephyr } from 'zephyr-rspack-plugin';

const mfConfig = {
  name: 'my-app',
  remotes: {
    'shared-ui': 'shared_ui@http://localhost:3001/remoteEntry.js',
  },
  shared: {
    react: { singleton: true },
    'react-dom': { singleton: true },
  },
};

export default composePlugins(
  withNx(),
  withReact(),
  withModuleFederation(mfConfig),
  withZephyr(), // Add Zephyr plugin
  (config) => {
    return config;
  }
);
```

--------------------------------

### Configure Zephyr Plugin with Rspack Directly

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rspack-plugin/README.md

Example configuration for standalone Rspack projects. This shows how to directly integrate the `withZephyr` function into your Rspack configuration.

```javascript
// rspack.config.js
const { withZephyr } = require('zephyr-rspack-plugin');

const config = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
  },
  // ... other Rspack configuration
};

module.exports = withZephyr()(config);
```

--------------------------------

### Configure Rollup Plugin Zephyr in rollup.config.js

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/rollup-plugin-zephyr/README.md

Integrate the zephyrPlugin into your Rollup configuration file (rollup.config.js). This example shows a basic setup for input, output, and including the plugin.

```javascript
// rollup.config.js
import { zephyrPlugin } from 'rollup-plugin-zephyr';

export default {
  input: 'src/main.js',
  output: {
    dir: 'dist',
    format: 'es',
  },
  plugins: [
    // ... other plugins
    zephyrPlugin(),
  ],
};
```

--------------------------------

### Integrate ESLint React Plugin for Recommended Rules

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/examples/vite-react-mf/host/README.md

This snippet demonstrates how to integrate the `eslint-plugin-react` into your ESLint configuration for a React project. It includes setting the React version and enabling recommended rules from both the base `recommended` and `jsx-runtime` configurations of the plugin.

```javascript
// eslint.config.js
import react from 'eslint-plugin-react';

export default tseslint.config({
  // Set the react version
  settings: { react: { version: '18.3' } },
  plugins: {
    // Add the react plugin
    react,
  },
  rules: {
    // other rules...
    // Enable its recommended rules
    ...react.configs.recommended.rules,
    ...react.configs['jsx-runtime'].rules,
  },
});
```

--------------------------------

### Install Parcel Reporter Zephyr Plugin (Package Managers)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/parcel-reporter-zephyr/README.md

These commands show how to install the parcel-reporter-zephyr plugin using various package managers like npm, yarn, pnpm, and bun. This is a dev dependency for your Parcel project.

```bash
# npm
npm install --save-dev parcel-reporter-zephyr

# yarn
yarn add --dev parcel-reporter-zephyr

# pnpm
pnpm add --dev parcel-reporter-zephyr

# bun
bun add --dev parcel-reporter-zephyr
```

--------------------------------

### Install Zephyr Repack Plugin (npm, yarn, pnpm, bun)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-repack-plugin/README.md

Instructions for installing the zephyr-repack-plugin using various package managers: npm, yarn, pnpm, and bun. This plugin is a development dependency.

```bash
npm install --save-dev zephyr-repack-plugin
yarn add --dev zephyr-repack-plugin
pnpm add --dev zephyr-repack-plugin
bun add --dev zephyr-repack-plugin
```

--------------------------------

### Install Zephyr Webpack Plugin (npm, yarn, pnpm, bun)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-webpack-plugin/README.md

Installs the zephyr-webpack-plugin package as a development dependency across different package managers.

```bash
# npm
npm install --save-dev zephyr-webpack-plugin

# yarn
yarn add --dev zephyr-webpack-plugin

# pnpm
pnpm add --dev zephyr-webpack-plugin

# bun
bun add --dev zephyr-webpack-plugin
```

--------------------------------

### Install vite-plugin-zephyr using npm, yarn, pnpm, or bun

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/vite-plugin-zephyr/README.md

Installs the vite-plugin-zephyr package as a development dependency across various package managers.

```bash
# npm
npm install --save-dev vite-plugin-zephyr

# yarn
yarn add --dev vite-plugin-zephyr

# pnpm
pnpm add --dev vite-plugin-zephyr

# bun
bun add --dev vite-plugin-zephyr
```

--------------------------------

### Zephyr Agent Build and Test Commands (Bash)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-agent/README.md

This snippet provides standard command-line instructions for building, testing, and running the Zephyr agent in development mode using npm. These are essential commands for developers working on Zephyr integrations and plugins. It assumes Node.js and npm are installed.

```bash
# Build the agent
npm run build

# Run tests
npm run test

# Development mode
npm run dev
```

--------------------------------

### Install Rollup Plugin Zephyr with npm, yarn, pnpm, or bun

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/rollup-plugin-zephyr/README.md

Install the rollup-plugin-zephyr package as a development dependency using various package managers. This is the first step before integrating the plugin into your Rollup build process.

```bash
# npm
npm install --save-dev rollup-plugin-zephyr

# yarn
yarn add --dev rollup-plugin-zephyr

# pnpm
pnpm add --dev rollup-plugin-zephyr

# bun
bun add --dev rollup-plugin-zephyr
```

--------------------------------

### Install Zephyr Modern.js Plugin (npm, yarn, pnpm, bun)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-modernjs-plugin/README.md

Installs the zephyr-modernjs-plugin package as a development dependency across various package managers. This is the first step to integrate Zephyr Cloud deployment into a Modern.js project.

```bash
# npm
npm install --save-dev zephyr-modernjs-plugin

# yarn
yarn add --dev zephyr-modernjs-plugin

# pnpm
pnpm add --dev zephyr-modernjs-plugin

# bun
bun add --dev zephyr-modernjs-plugin
```

--------------------------------

### Automatic Naming Convention Examples (JSON)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-agent/README.md

Illustrates how Zephyr automatically determines project and app names based on package.json content when a Git repository with a remote origin is not found. This includes scoped packages and different package.json structures.

```json
# Examples of automatic naming:
# package.json: { "name": "@my-company/my-app" }
# → org: "jwt-username", project: "my-company", app: "my-app"

# package.json: { "name": "my-project" } (no root package.json)
# → org: "jwt-username", project: "my-project", app: "my-project"
```

--------------------------------

### Configure Zephyr Plugin with Module Federation Plugin

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-webpack-plugin/README.md

Demonstrates integrating the Zephyr plugin alongside the `@module-federation/webpack` plugin. This setup is common for microfrontend architectures.

```javascript
// webpack.config.js
const ModuleFederationPlugin = require('@module-federation/webpack');
const { withZephyr } = require('zephyr-webpack-plugin');

const config = {
  entry: './src/index.js',
  plugins: [
    new ModuleFederationPlugin({
      name: 'host',
      remotes: {
        mfe1: 'mfe1@http://localhost:3001/remoteEntry.js',
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
  ],
  // ... other configuration
};

module.exports = withZephyr()(config);
```

--------------------------------

### Build Zephyr Packages Project

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/with-zephyr/README.md

Provides commands for building the Zephyr Packages project, which is written in TypeScript. It includes steps for installing dependencies, building the project, running in development mode with watch, and type checking.

```bash
# Install dependencies
pnpm install

# Build the project
pnpm run build

# Development mode with watch
pnpm run dev

# Type checking
pnpm run typecheck
```

--------------------------------

### Configure Zephyr Plugin with TypeScript and Rspack

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rspack-plugin/README.md

Example configuration for Rspack projects using TypeScript. This demonstrates integrating the `withZephyr` function into a TypeScript-based Rspack configuration, ensuring type safety.

```typescript
// rspack.config.ts
import { Configuration } from '@rspack/core';
import { withZephyr } from 'zephyr-rspack-plugin';

const config: Configuration = {
  entry: './src/index.tsx',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
  },
  // ... other configuration
};

export default withZephyr()(config);
```

--------------------------------

### with-zephyr Command Line Options (Bash)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/with-zephyr/README.md

Demonstrates various command-line options for the with-zephyr codemod, including dry runs, automatic package installation, specifying target directories, and filtering by bundler type.

```bash
# Show what would be changed without modifying files
npx with-zephyr --dry-run

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

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

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

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

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

--------------------------------

### Configure Zephyr Plugin in Rolldown (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rolldown-plugin/README.md

Example demonstrating the integration of the `withZephyr()` plugin within a TypeScript Rolldown configuration file (`rolldown.config.ts`).

```typescript
// rolldown.config.ts
import { defineConfig } from 'rolldown';
import { withZephyr } from 'zephyr-rolldown-plugin';

export default defineConfig({
  input: 'src/main.tsx',
  plugins: [
    // ... other plugins
    withZephyr(),
  ],
});
```

--------------------------------

### Create Zephyr-enabled React Native App

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-repack-plugin/README.md

This bash command is used to create a new React Native application pre-configured with Zephyr. It ensures that the application is set up with Zephyr enabled and ready for use, simplifying the initial project setup process.

```bash
npx create-zephyr-apps@latest

```

--------------------------------

### Configure Zephyr Plugin in Rolldown (JavaScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rolldown-plugin/README.md

Example of how to add the `withZephyr()` plugin to a Rolldown configuration file (`rolldown.config.mjs`). It includes a custom 'emit-html' plugin and demonstrates the placement of the Zephyr plugin.

```javascript
// rolldown.config.mjs
import { defineConfig } from 'rolldown';
import { withZephyr } from 'zephyr-rolldown-plugin';

export default defineConfig({
  input: 'src/main.tsx',
  plugins: [
    {
      name: 'emit-html',
      generateBundle() {
        const html = `
          <html>
            <body>
              <div id="root"></div>
              <script type="module" src="./main.js"></script>
            </body>
          </html>
        `;
        this.emitFile({
          type: 'asset',
          fileName: 'index.html',
          source: html,
        });
      },
    },
    withZephyr(), // Add Zephyr plugin
  ],
});
```

--------------------------------

### Zephyr Plugin with Module Federation in Rsbuild

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rsbuild-plugin/README.md

Configures the Zephyr plugin alongside the Module Federation plugin in Rsbuild. This setup is for microfrontend architectures, enabling communication between remote and host applications.

```typescript
// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
import { withZephyr } from 'zephyr-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: 'my-app',
      remotes: {
        'shared-ui': 'shared_ui@http://localhost:3001/remoteEntry.js',
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
    withZephyr(), // Add after Module Federation
  ],
});
```

--------------------------------

### Configure ESLint for Type-Aware Linting in Vite/React/TypeScript

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/examples/vite-react-mf/host/README.md

This snippet shows how to configure ESLint in a Vite/React/TypeScript project to enable type-aware linting rules. It requires specifying project configuration files (`tsconfig.node.json`, `tsconfig.app.json`) and the root directory for TypeScript parsing.

```javascript
export default tseslint.config({
  languageOptions: {
    // other options...
    parserOptions: {
      project: ['./tsconfig.node.json', './tsconfig.app.json'],
      tsconfigRootDir: import.meta.dirname,
    },
  },
});
```

--------------------------------

### TypeScript Configuration for Rollup Plugin Zephyr

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/rollup-plugin-zephyr/README.md

Set up the zephyrPlugin in a TypeScript Rollup configuration file (rollup.config.ts). This example uses defineConfig from Rollup for type safety and clarity.

```typescript
// rollup.config.ts
import { defineConfig } from 'rollup';
import { zephyrPlugin } from 'rollup-plugin-zephyr';

export default defineConfig({
  input: 'src/main.ts',
  output: {
    dir: 'dist',
    format: 'es',
  },
  plugins: [zephyrPlugin()],
});
```

--------------------------------

### Configure Zephyr Plugin in Rspress

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rspress-plugin/README.md

Example of how to add the Zephyr plugin to your Rspress configuration file (rspress.config.ts or rspress.config.js). This enables automatic static asset upload and global CDN distribution.

```typescript
import { defineConfig } from 'rspress/config';
import { withZephyr } from 'zephyr-rspress-plugin';

export default defineConfig({
  ssg: true,
  plugins: [withZephyr()],
});
```

--------------------------------

### Configure Zephyr Plugin with Standalone Webpack

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-webpack-plugin/README.md

Applies the Zephyr plugin to a standard Webpack configuration. This example shows how to use `require` for the plugin and merge it with an existing config object.

```javascript
// webpack.config.js
const { withZephyr } = require('zephyr-webpack-plugin');

const config = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
  },
  // ... other Webpack configuration
};

module.exports = withZephyr()(config);
```

--------------------------------

### Configure Zephyr Plugin with Rspack

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-modernjs-plugin/README.md

Demonstrates how to configure the Zephyr plugin within a Modern.js project when using the Rspack bundler. This setup ensures that the Zephyr plugin is correctly initialized alongside the Rspack bundler configuration.

```typescript
plugins: [
  appTools({
    bundler: 'rspack',
  }),
  withZephyr(),
];
```

--------------------------------

### Webpack Integration: ZephyrWebpackPlugin (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-xpack-internal/README.md

Example implementation of a Webpack plugin that leverages Zephyr XPack utilities, such as extracting federation configuration and building an assets map during the compilation process.

```typescript
// Webpack plugin integration
class ZephyrWebpackPlugin {
  apply(compiler) {
    // Use xpack utilities
    const federationConfig = extractFederationConfig(compiler.options);
    const assetsMap = buildWebpackAssetsMap(compilation);
  }
}
```

--------------------------------

### TypeScript Utility Function Examples

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-edge-contract/README.md

Demonstrates the usage of various utility functions provided by the Zephyr Edge Contract package, including promise utilities for deferred and lazy loading, string manipulation for ANSI code stripping, and ID generation for applications and snapshots.

```typescript
// Deferred promise implementation
const deferred = createDeferred<T>();

// Lazy promise loading
const lazyPromise = createLazyPromise(() => expensiveOperation());

// Controlled concurrency
await forEachLimit(items, 3, async (item) => processItem(item));

// Strip ANSI color codes
const cleanText = stripAnsi(coloredText);

// String validation and parsing
const isValid = validateString(input, schema);

// Generate application UID
const appUid = createApplicationUid(packageName, version);

// Create snapshot ID
const snapshotId = createSnapshotId(buildInfo);
```

--------------------------------

### Custom Webpack Configuration with Zephyr Plugin (JavaScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-webpack-plugin/README.md

This JavaScript code demonstrates a custom Webpack configuration file (webpack.config.js) that integrates the zephyr-webpack-plugin. It includes common Webpack configurations like entry points, code splitting, module resolution, and Babel loading, all enhanced by the `withZephyr` higher-order function for deployment and environment settings. Ensure Webpack 5.x+ and Node.js 18+ are installed.

```javascript
// webpack.config.js
const { withZephyr } = require('zephyr-webpack-plugin');

const config = {
  entry: './src/index.js',
  optimization: {
    splitChunks: {
      chunks: 'all',
    },
  },
  resolve: {
    extensions: ['.js', '.jsx', '.ts', '.tsx'],
  },
  module: {
    rules: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        exclude: /node_modules/,
        use: 'babel-loader',
      },
    ],
  },
};

module.exports = withZephyr({
  deploy: process.env.NODE_ENV === 'production',
  environment: process.env.NODE_ENV || 'development',
})(config);
```

--------------------------------

### Configure ESLint for TypeScript Type-Aware Rules

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/examples/vite-react-ts/README.md

This snippet demonstrates how to configure ESLint to enable type-aware linting rules for TypeScript projects. It involves updating parserOptions in the ESLint configuration file and extending specific TypeScript ESLint plugins. Ensure `tsconfig.json` and `tsconfig.node.json` are correctly referenced.

```javascript
export default {
  // other rules...
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: ['./tsconfig.json', './tsconfig.node.json'],
    tsconfigRootDir: __dirname,
  },
};
```

--------------------------------

### TypeScript Constants and Enums for Zephyr

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-edge-contract/README.md

Provides examples of exported constants and enums used within the Zephyr ecosystem for API versions, build environments, and plugin types. These predefined values ensure consistency and facilitate configuration management.

```typescript
// API versions
export const API_VERSIONS = {
  V1: 'v1',
  V2: 'v2',
  CURRENT: 'v2',
} as const;

// Build environments
export const ENVIRONMENTS = {
  DEVELOPMENT: 'development',
  STAGING: 'staging',
  PRODUCTION: 'production',
} as const;

// Plugin types
export const PLUGIN_TYPES = {
  WEBPACK: 'webpack',
  RSPACK: 'rspack',
  VITE: 'vite',
  ROLLUP: 'rollup',
} as const;
```

--------------------------------

### TypeScript Zephyr Error Interface

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-edge-contract/README.md

Defines the structure for standardized error objects within the Zephyr ecosystem, including error codes, messages, and optional details. Also shows an example of a utility function for creating these error objects.

```typescript
interface ZephyrError {
  code: string;
  message: string;
  details?: Record<string, any>;
  stack?: string;
}

// Error creation utilities
const error = createZephyrError('INVALID_CONFIG', 'Configuration is invalid');
```

--------------------------------

### Run create-zephyr-apps CLI in interactive mode

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/create-zephyr-apps/README.md

Instructions to launch the create-zephyr-apps CLI in interactive mode, which prompts the user for project name, template type, build tool, and other configurations.

```bash
npx create-zephyr-apps@latest
```

--------------------------------

### Initialize and Deploy with Zephyr Agent (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-agent/README.md

Demonstrates how to initialize the ZephyrAgent with build context and assets, and then initiate a deployment to Zephyr Cloud. This is the primary interaction method for public Zephyr plugins.

```typescript
import { ZephyrAgent } from 'zephyr-agent';

// Initialize the agent
const agent = new ZephyrAgent({
  buildContext: buildInfo,
  assets: assetMap,
});

// Deploy to Zephyr Cloud
await agent.deploy();
```

--------------------------------

### Build Application for Production with pnpm

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/README.md

Builds the application for production deployment. This command compiles and optimizes the project assets for a production environment.

```shell
pnpm build
```

--------------------------------

### Run Production Build with pnpm

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/README.md

Runs the production build of the application. This command executes the already built production-ready version of the project.

```shell
pnpm start
```

--------------------------------

### Zephyr Rsbuild Plugin API Reference

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rsbuild-plugin/README.md

Details on how to use the `withZephyr` function to configure the Zephyr Rsbuild plugin.

```APIDOC
## withZephyr(options?)

### Description
Creates an Rsbuild plugin for Zephyr integration.

### Method
`withZephyr`

### Parameters
#### Options
- **options** (object) - Optional configuration options.
  - **wait_for_index_html** (boolean) - Optional. Wait for HTML processing before deployment.

### Returns
An Rsbuild plugin that can be added to the plugins array in the Rsbuild configuration.

### Example Usage
```javascript
// rsbuild.config.js
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { withZephyr } from 'zephyr-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReact(),
    withZephyr({ // Add Zephyr plugin with options
      wait_for_index_html: true
    }),
  ],
});
```
```

--------------------------------

### Basic Rsbuild Configuration with Zephyr

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rsbuild-plugin/README.md

How to add the Zephyr plugin to your Rsbuild configuration for basic deployment.

```APIDOC
## Basic Setup

Add the plugin to your Rsbuild configuration:

```javascript
// rsbuild.config.js
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { withZephyr } from 'zephyr-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReact(),
    withZephyr(), // Add Zephyr plugin
  ],
});
```
```

--------------------------------

### Rsbuild Configuration with Module Federation and Zephyr

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rsbuild-plugin/README.md

Integrating Zephyr plugin with Module Federation for microfrontend architectures.

```APIDOC
## With Module Federation

```typescript
// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
import { withZephyr } from 'zephyr-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: 'my-app',
      remotes: {
        'shared-ui': 'shared_ui@http://localhost:3001/remoteEntry.js',
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
    withZephyr(), // Add after Module Federation
  ],
});
```
```

--------------------------------

### Build Snapshot Creation (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/docs/CONTRIBUTING.md

Details the process of creating a build snapshot, which involves generating metadata about the build and including dependency information for deployment tracking and analysis.

```typescript
// Create build snapshot
// Generate metadata about the build
// Include dependency information
```

--------------------------------

### Zephyr Agent Connection for Deployment (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/docs/CONTRIBUTING.md

Outlines the steps for connecting to the Zephyr agent to perform deployment operations, including uploading assets, snapshots, and build statistics, as well as handling deployment configurations.

```typescript
// Connect to the Zephyr agent for deployment
// Upload assets
// Upload snapshot
// Upload build stats
// Handle deployment configuration
```

--------------------------------

### Rsbuild Project Build Scripts

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rsbuild-plugin/README.md

Defines standard build scripts (dev, build, preview) for an Rsbuild project in the package.json file. These scripts leverage the Rsbuild CLI for development and production builds.

```json
{
  "scripts": {
    "dev": "rsbuild dev",
    "build": "rsbuild build",
    "preview": "rsbuild preview"
  }
}
```

--------------------------------

### Rspress Build Scripts

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rspress-plugin/README.md

Defines common build scripts for an Rspress project in package.json. Running 'build' or 'build:prod' with the Zephyr plugin enabled will deploy your site to Zephyr Cloud.

```json
{
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "build:prod": "NODE_ENV=production rspress build"
  }
}
```

--------------------------------

### Module Federation Processing (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/docs/CONTRIBUTING.md

Covers the implementation steps for handling module federation, including extracting configurations, managing remote dependencies, and enabling runtime replacement. Essential for micro-frontend architectures.

```typescript
// Process module federation (if applicable)
// Extract host/remote configurations
// Handle and replace remote dependency URLs
// Enable runtime replacement
```

--------------------------------

### Asset Management: Upload Agent Initialization (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-xpack-internal/README.md

Initializes an upload agent for assets, bundling together the assets map, federation configuration, and build statistics for upload.

```typescript
// Upload agent for assets
const uploadAgent = new ZeXpackUploadAgent({
  assets: assetsMap,
  federation: federationConfig,
  buildStats: stats,
});

await uploadAgent.upload();
```

--------------------------------

### Deployment Asset Upload and Management (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-agent/README.md

This snippet shows essential functions for the deployment process, including uploading build assets to a CDN, enabling environments on edge servers, and uploading build statistics. These operations are crucial for deploying applications and tracking their performance. It requires configurations for upload strategies and snapshot IDs.

```typescript
// Upload assets to CDN
await uploadAssets(assets, uploadStrategy);

// Enable environment on edge
await enableSnapshotOnEdge(snapshotId);

// Upload build statistics
await uploadBuildStats(buildStats);
```

--------------------------------

### Read Package Information and Git Details (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-agent/README.md

This snippet demonstrates how to extract package.json information and Git repository details using asynchronous functions. It's a core part of setting up the build context by reading project metadata. Dependencies include utility functions for reading package.json and Git info.

```typescript
const packageInfo = await readPackageJson(projectRoot);

// Get Git repository information
const gitInfo = await getGitInfo();

// Parse Zephyr dependencies
const deps = parseZephyrDependencies(packageJson);
```

--------------------------------

### Automated Patch Version Bump with pnpm

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/README.md

Automates the patch version release process across all packages in the monorepo. This includes updating version numbers, creating commits, tagging releases, and optionally opening a PR.

```shell
pnpm bump-patch
```

--------------------------------

### Add build scripts to package.json for Vite projects

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/vite-plugin-zephyr/README.md

Includes standard scripts for `dev`, `build`, and `preview` commands using Vite, commonly added to a project's `package.json` file.

```json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}
```

--------------------------------

### Run Test Suite with pnpm

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/README.md

Executes the project's test suite to ensure code quality and functionality. This is crucial for verifying the integrity of the plugins and utilities.

```shell
pnpm test
```

--------------------------------

### Run with-zephyr Codemod (Bash)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/with-zephyr/README.md

Executes the with-zephyr codemod tool to automatically integrate Zephyr plugins into bundler configurations. This is the recommended method for quickly setting up Zephyr for micro-frontend deployments.

```bash
curl -fsSL https://with.zephyr-cloud.io | node

# Alternative methods:
npx with-zephyr
pnpm dlx with-zephyr
yarn dlx with-zephyr
bunx with-zephyr
```

--------------------------------

### Modern.js Build Scripts for Zephyr Deployment

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-modernjs-plugin/README.md

Includes essential npm scripts in the `package.json` file for running a Modern.js application with Zephyr integration. These scripts facilitate development (`dev`), building (`build`), and serving (`serve`) the application.

```json
{
  "scripts": {
    "dev": "modern dev",
    "build": "modern build",
    "serve": "modern serve"
  }
}
```

--------------------------------

### Add Build Scripts to package.json

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-rspack-plugin/README.md

Defines essential build scripts for Rspack projects, including development server (`rspack serve`), production build (`rspack build`), and optimized production build (`NODE_ENV=production rspack build`). These scripts are added to the `package.json` file.

```json
{
  "scripts": {
    "dev": "rspack serve",
    "build": "rspack build",
    "build:prod": "NODE_ENV=production rspack build"
  }
}
```

--------------------------------

### Basic Zephyr Repack Plugin Usage (JavaScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-repack-plugin/README.md

Demonstrates the basic usage of the zephyr-repack-plugin by wrapping the Rspack configuration. It imports the `withZephyr` function and applies it to the Rspack config object.

```javascript
const { withZephyr } = require('zephyr-repack-plugin');

const config = {
  /** ...rspack configuration */
};

module.exports = withZephyr()(config);
```

--------------------------------

### Nx Command for Generating Webpack App with Module Federation (Bash)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-webpack-plugin/README.md

This bash command uses the Nx CLI to generate a new React application with Webpack as the bundler and Module Federation enabled. This sets up a project structure suitable for micro-frontends. After generation, you would typically add the Zephyr plugin to the generated Webpack configuration.

```bash
# Generate a new Webpack app with Module Federation
nx g @nx/react:app my-app --bundler=webpack --mf=true

# Add Zephyr plugin to the generated configuration
```

--------------------------------

### Asset Extraction Logic (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/docs/CONTRIBUTING.md

Illustrates the process of identifying and extracting all necessary assets required for deployment, including generating partial asset maps. This is a key step in preparing build artifacts for Zephyr.

```typescript
// Extract asset information from the build
// Identify all assets required for deployment
// Generate [asset maps](libs/zephyr-agent/src/lib/node-persist/partial-assets-map.ts)
```

--------------------------------

### Format Code with pnpm

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/README.md

Formats the codebase using Prettier to ensure consistent code style. This command automatically adjusts code formatting according to the project's standards.

```shell
pnpm format
```

--------------------------------

### MDX Component Usage in Rspress

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/examples/rspress-ssg/docs/guide/index.md

Demonstrates how to import and use React components within an MDX file in Rspress. Requires files to have the '.mdx' extension and components to be imported before use.

```mdx
// docs/index.mdx
import { CustomComponent } from './custom';

# Hello world

<CustomComponent />
```

--------------------------------

### Code Blocks in Rspress Markdown

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/examples/rspress-ssg/docs/guide/index.md

Demonstrates basic code block syntax in Rspress Markdown, including adding custom titles to code blocks. Supports standard Markdown code fences.

```markdown
```js
console.log('Hello World');
```

```js title="hello.js"
console.log('Hello World');
```
```

--------------------------------

### Build Zephyr Package

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-xpack-internal/README.md

This command builds the Zephyr package. It is a standard npm script for compiling the project.

```bash
# Build the package
npm run build
```

--------------------------------

### Custom Containers in Rspress Markdown

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/examples/rspress-ssg/docs/guide/index.md

Illustrates the use of triple colons (:::) syntax in Rspress Markdown to create custom content blocks with predefined types (tip, info, warning, danger, details) and custom titles.

```markdown
:::tip
This is a `block` of type `tip`
:::

:::info
This is a `block` of type `info`
:::

:::warning
This is a `block` of type `warning`
:::

:::danger
This is a `block` of type `danger`
:::

::: details
This is a `block` of type `details`
:::

:::tip Custom Title
This is a `block` of `Custom Title`
:::

:::tip{title="Custom Title"}
This is a `block` of `Custom Title`
:::
```

--------------------------------

### Lint Code with pnpm

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/README.md

Checks the codebase for linting errors using configured linters. This helps maintain code style consistency and identify potential issues.

```shell
pnpm lint
```

--------------------------------

### Configure Federation Dashboard Plugin

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-xpack-internal/README.md

This snippet demonstrates the configuration of the Federation Dashboard Plugin for advanced federation analytics. It includes options for specifying the filename for stats, and whether to include modules and dependencies.

```typescript
// Advanced federation analytics
const dashboardPlugin = new FederationDashboardPlugin({
  filename: 'federation-stats.json',
  includeModules: true,
  includeDependencies: true,
  computeVersionStrategy: true,
});
```

--------------------------------

### Module Federation Configuration with Re.Pack (JavaScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-repack-plugin/README.md

Illustrates how to configure Module Federation using Re.Pack's `ModuleFederationPluginV2` within an Rspack configuration file. It includes settings for remotes and shared dependencies.

```javascript
// rspack.config.js
plugins: [
  new Repack.plugins.ModuleFederationPluginV2({
    // your configuration
  }),
];
```

```javascript
// rspack.config.js
... 
 new Repack.plugins.ModuleFederationPluginV2({
        /**
         * The name of the module is used to identify the module in URLs resolver and imports.
         */
        name: 'MobileHost',
        dts: false,
        remotes: {
          MobileCart: `MobileCart@http://localhost:9000/${platform}/MobileCart.container.js.bundle`,
          MobileInventory: `MobileInventory@http://localhost:9001/${platform}/MobileInventory.container.js.bundle`,
          MobileCheckout: `MobileCheckout@http://localhost:9002/${platform}/MobileCheckout.container.js.bundle`,
          MobileOrders: `MobileOrders@http://localhost:9003/${platform}/MobileOrders.container.js.bundle`,
        },
        /**
         * Shared modules are shared in the share scope.
         * React, React Native and React Navigation should be provided here because there should be only one instance of these modules.
         * Their names are used to match requested modules in this compilation.
         */
        shared: getSharedDependencies({eager: true}),
      }),
...
```

--------------------------------

### Versioning: Compute Version Strategy (TypeScript)

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-xpack-internal/README.md

Computes the versioning strategy for federated modules by combining information from package.json, git context, and build context.

```typescript
// Compute version strategy for federation
const versionStrategy = computeVersionStrategy({
  packageJson: packageInfo,
  gitInfo: gitContext,
  buildContext: buildInfo,
});
```

--------------------------------

### Run Zephyr Integration Tests with Mock Data

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-xpack-internal/README.md

This command runs integration tests for the Zephyr package using mock data. It is a specialized npm script for testing integration scenarios.

```bash
# Test with mock data
npm run test:integration
```

--------------------------------

### Package.json Build Scripts for Webpack

Source: https://github.com/zephyrcloudio/zephyr-packages/blob/main/libs/zephyr-webpack-plugin/README.md

Adds essential build scripts to a project's `package.json` file for running Webpack development server, standard builds, and production builds.

```json
{
  "scripts": {
    "dev": "webpack serve",
    "build": "webpack",
    "build:prod": "NODE_ENV=production webpack"
  }
}
```
Tokens:
Raw