or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-vitejs--plugin-react-refresh

Provides React Refresh support for Vite development server with hot module replacement capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vitejs/plugin-react-refresh@1.3.x

To install, run

npx @tessl/cli install tessl/npm-vitejs--plugin-react-refresh@1.3.0

index.mddocs/

@vitejs/plugin-react-refresh

@vitejs/plugin-react-refresh is a Vite plugin that provides React Refresh (Fast Refresh) support for React applications during development. It integrates with Vite's development server to enable hot module replacement (HMR) that preserves React component state while reloading code changes, providing instant feedback during development with minimal configuration.

Package Information

  • Package Name: @vitejs/plugin-react-refresh
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install @vitejs/plugin-react-refresh

Core Imports

import reactRefresh from '@vitejs/plugin-react-refresh';

For CommonJS:

const reactRefresh = require('@vitejs/plugin-react-refresh');

Basic Usage

// vite.config.js
import reactRefresh from '@vitejs/plugin-react-refresh';

export default {
  plugins: [reactRefresh()]
};

With TypeScript:

// vite.config.ts
import { defineConfig } from 'vite';
import reactRefresh from '@vitejs/plugin-react-refresh';

export default defineConfig({
  plugins: [reactRefresh()]
});

Architecture

The plugin operates at build time as part of Vite's plugin system:

  • Plugin Factory: Main export is a function that returns a Vite plugin object
  • Babel Integration: Uses Babel plugins to transform React components with refresh boundaries
  • Runtime Injection: Automatically injects React Refresh runtime code into the development bundle
  • File Processing: Processes JSX/TSX files matching configurable include/exclude patterns
  • Development Only: Automatically disables in production builds

Capabilities

Plugin Factory

Creates a Vite plugin with React Refresh support.

/**
 * Creates a Vite plugin that enables React Refresh for development
 * @param options - Optional configuration for the plugin
 * @returns Vite plugin object with React Refresh capabilities
 */
function reactRefresh(options?: Options): import('vite').Plugin;

Usage Examples:

// Basic usage
import reactRefresh from '@vitejs/plugin-react-refresh';

export default {
  plugins: [reactRefresh()]
};

// With custom parser plugins for experimental syntax
export default {
  plugins: [
    reactRefresh({
      parserPlugins: ['classProperties', 'classPrivateProperties']
    })
  ]
};

// With custom include/exclude patterns
export default {
  plugins: [
    reactRefresh({
      include: '**/*.tsx',
      exclude: [/\.stories\.(t|j)sx?$/, /node_modules/]
    })
  ]
};

Preamble Code Access

Access to the preamble code used for React Refresh runtime setup.

/**
 * Preamble code injected into HTML for React Refresh runtime initialization
 * @type {string}
 */
reactRefresh.preambleCode: string;

Usage Example:

// Access preamble code for custom HTML injection
import reactRefresh from '@vitejs/plugin-react-refresh';

console.log(reactRefresh.preambleCode);
// Contains the runtime setup code for React Refresh

Types

Options Interface

Configuration options for the React Refresh plugin.

interface Options {
  /** 
   * Additional Babel parser plugins to enable for experimental syntax
   * @example ['classProperties', 'decorators-legacy'] 
   */
  parserPlugins?: ParserOptions['plugins'];
  
  /** 
   * Files to include for React Refresh processing
   * @default /\.(t|j)sx?$/
   * @example '**/*.tsx' or [/\.tsx$/, /\.jsx$/]
   */
  include?: string | RegExp | Array<string | RegExp>;
  
  /** 
   * Files to exclude from React Refresh processing  
   * @default /node_modules/
   * @example [/\.stories\.(t|j)sx?$/, /node_modules/]
   */
  exclude?: string | RegExp | Array<string | RegExp>;
}

Plugin Type

Vite plugin object returned by the factory function. The plugin conforms to Vite's Plugin interface and implements the following hooks:

// The plugin returns a standard Vite Plugin object with these key properties:
interface ReactRefreshPlugin extends import('vite').Plugin {
  /** Plugin identifier */
  name: 'react-refresh';
  
  /** Plugin execution order - runs before other plugins */
  enforce: 'pre';
}

Babel Parser Options

Extended from @babel/core for parser plugin configuration.

type ParserOptions = {
  /** 
   * Babel parser plugins to enable
   * @example ['jsx', 'typescript', 'decorators-legacy']
   */
  plugins?: string[];
};

Error Handling

The plugin handles several error scenarios:

  • Missing Preamble: Throws error if React Refresh runtime preamble is not detected
  • Build Mode: Automatically skips processing in production builds
  • Invalid Files: Silently skips files that don't match include/exclude patterns
  • Non-React Files: Skips plain JS/TS files without React imports

Middleware Mode Error

When using Vite in middleware mode, you may encounter this error:

@vitejs/plugin-react-refresh can't detect preamble. Something is wrong. 
See https://github.com/vitejs/vite-plugin-react/pull/11#discussion_r430879201

This occurs when your entry index.html file is not transformed with ViteDevServer.transformIndexHtml.

Solution: Explicitly transform your index.html in your server setup:

app.get('/', async (req, res, next) => {
  try {
    let html = fs.readFileSync(path.resolve(root, 'index.html'), 'utf-8')
    html = await viteServer.transformIndexHtml(req.url, html)
    res.send(html)
  } catch (e) {
    return next(e)
  }
})

Development Notes

  • File Processing: By default processes .js, .jsx, .ts, and .tsx files
  • Node.js Version: Requires Node.js 12.0.0 or higher
  • React Components: Automatically detects React components by uppercase naming convention
  • TypeScript Support: Full support for TypeScript JSX syntax
  • ReasonReact: Special handling for ReasonReact .bs.js files
  • Middleware Mode: Requires explicit HTML transformation in custom server setups