@coze-arch/vite-plugin-react-refresh-cloudide

Vite plugin that fixes React Fast Refresh in CloudIDE environments by intercepting virtual module requests.

Problem

In certain CloudIDE environments, Vite's virtual module resolution for React Fast Refresh (/node_modules/@react-refresh) may fail with 404 errors due to path resolution issues between the plugin's resolveId/load hooks and the actual HTTP request handling.

Solution

This plugin uses Vite's HTTP middleware to directly intercept and serve the React refresh runtime file, bypassing the virtual module resolution system entirely.

Installation

npm install -D @coze-arch/vite-plugin-react-refresh-cloudide
# or
pnpm add -D @coze-arch/vite-plugin-react-refresh-cloudide
# or
yarn add -D @coze-arch/vite-plugin-react-refresh-cloudide

Usage

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import cloudIDEReactRefresh from '@coze-arch/vite-plugin-react-refresh-cloudide';

export default defineConfig({
  plugins: [
    cloudIDEReactRefresh(), // Must be placed before @vitejs/plugin-react
    react()
  ]
});

Options

interface CloudIDEReactRefreshOptions {
  /**
   * Enable debug logging
   * @default false
   */
  debug?: boolean;

  /**
   * Custom paths to intercept
   * @default ['/node_modules/react-refresh.js', '/node_modules/@react-refresh', '/node_modules/@react-refresh.js']
   */
  interceptPaths?: string[];

  /**
   * Custom path to refresh-runtime.js
   * If not provided, will auto-detect from @vitejs/plugin-react
   */
  refreshRuntimePath?: string;
}

Example with options

export default defineConfig({
  plugins: [
    cloudIDEReactRefresh({
      debug: true, // Enable debug logging
      interceptPaths: ['/custom-path/react-refresh.js'] // Custom intercept paths
    }),
    react()
  ]
});

How it works

1. Intercepts HTTP requests: Uses Vite's configureServer hook to add middleware that intercepts requests to React refresh runtime paths
2. Reads the actual file: Directly reads the refresh-runtime.js file from @vitejs/plugin-react
3. Serves the content: Returns the file content with proper headers, bypassing Vite's virtual module system

Debugging

Enable debug mode to see detailed logs:

cloudIDEReactRefresh({ debug: true })

You'll see logs like:

[CloudIDE Fix] Intercepted request: /node_modules/react-refresh.js
[CloudIDE Fix] Reading from: /path/to/refresh-runtime.js
[CloudIDE Fix] File exists: true
[CloudIDE Fix] Content loaded, length: 21234

Requirements

• Vite 5.x, 6.x, or 7.x
• @vitejs/plugin-react 4.x or 5.x

License

Apache-2.0