Zephyr Cloud Docs

    React + Rsbuild

    Prerequisites

    Overview

    Rsbuild is a Rspack-based build tool for the web that provides a fast and modern development experience. This guide shows you how to integrate Zephyr Cloud with your Rsbuild React application.

    Setup

    1. Create a new Rsbuild project

    Terminal
    npm create rsbuild@latest my-rsbuild-app

    Select these options:

    Terminal
    ? Select framework: React
? Select language: TypeScript

    Navigate to your project:

    Terminal
    cd my-rsbuild-app

    2. Install Zephyr Rsbuild Plugin

    Terminal
    npm install --save-dev zephyr-rsbuild-plugin

    3. Configure Rsbuild

    Update your rsbuild.config.ts file:

    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(), // Add Zephyr plugin
  ],
});

    4. Build and Deploy

    Info

    The first time you initiate a build with Zephyr, it will prompt you to log in by directing you to the Zephyr website. This login is required only on your first build; subsequent builds will not require a login.

    We may require you to log in again if you removed your Zephyr configuration file ~/.zephyr locally.

    Terminal
    npm run build

    Your application will be automatically deployed to Zephyr Cloud during the build process.

    Module Federation Support

    To add Module Federation support to your Rsbuild application:

    1. Install Module Federation Plugin

    Terminal
    npm install --save-dev @module-federation/rsbuild-plugin

    2. Configure Module Federation

    Update your rsbuild.config.ts:

    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: 'host',
      remotes: {
        remote: 'remote@http://localhost:3001/remoteEntry.js',
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
    withZephyr(), // Add Zephyr plugin after Module Federation
  ],
});

    Advanced Configuration

    You can pass options to the Zephyr plugin:

    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({
      wait_for_index_html: true, // Wait for HTML processing
    }),
  ],
});

    Next Steps

    Troubleshooting

    If you encounter issues:

    1. Build fails: Ensure you have the latest version of zephyr-rsbuild-plugin
    2. Module Federation errors: Make sure the Zephyr plugin is added after the Module Federation plugin
    3. Authentication issues: Check your Zephyr Cloud authentication with our browser extension

    For more help, visit our Discord community or check our error codes documentation.