@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

``bash
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

`ts
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

`ts
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;
}
`

$3

`ts
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:

`ts
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