CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pmmmwh--react-refresh-webpack-plugin

Webpack plugin to enable React Fast Refresh (Hot Reloading) for React components during development

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

plugin-configuration.mddocs/

Plugin Configuration

Comprehensive configuration options for the ReactRefreshPlugin to customize Fast Refresh behavior and integration.

Capabilities

ReactRefreshPlugin Constructor

Creates a new instance of the React Refresh Plugin with optional configuration.

/**
 * @param {ReactRefreshPluginOptions} [options] Options for react-refresh-plugin.
 */
constructor(options?: ReactRefreshPluginOptions);

Usage Example:

const ReactRefreshPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

const plugin = new ReactRefreshPlugin({
  exclude: /node_modules/,
  include: /\.[jt]sx?$/,
  forceEnable: false,
  overlay: {
    sockIntegration: 'wds'
  }
});

Apply Method

Applies the plugin to a Webpack compiler instance.

/**
 * Applies the plugin.
 * @param {import('webpack').Compiler} compiler A webpack compiler object.
 * @returns {void}
 */
apply(compiler: import('webpack').Compiler): void;

Usage Example:

// Automatically called by Webpack when plugin is added to plugins array
module.exports = {
  plugins: [
    new ReactRefreshPlugin(options)
  ]
};

Plugin Options

Main configuration interface for customizing plugin behavior.

interface ReactRefreshPluginOptions {
  /**
   * Enables strict ES Modules compatible runtime.
   */
  esModule?: boolean | ESModuleOptions;
  
  /**
   * Files to explicitly exclude from processing.
   */
  exclude?: string | RegExp | (string | RegExp)[];
  
  /**
   * Enables the plugin forcefully.
   */
  forceEnable?: boolean;
  
  /**
   * Files to explicitly include for processing.
   */
  include?: string | RegExp | (string | RegExp)[];
  
  /**
   * Name of the library bundle.
   */
  library?: string;
  
  /**
   * Modifies how the error overlay integration works in the plugin.
   */
  overlay?: boolean | ErrorOverlayOptions;
}

Force Enable Option

Enables the plugin forcefully, bypassing normal development mode checks.

forceEnable?: boolean;

Usage Examples:

// Enable in production (not recommended)
new ReactRefreshPlugin({
  forceEnable: true
});

// Enable with 'none' mode without NODE_ENV
new ReactRefreshPlugin({
  forceEnable: process.env.WEBPACK_MODE !== 'production'
});

Default: undefined

Use Cases:

  • Production usage (proceed at your own risk)
  • Usage with none mode in Webpack without setting NODE_ENV
  • Usage in unsupported environments like electron-prerender

Include/Exclude Options

Control which files are processed by the plugin using patterns similar to Webpack's module.rules.

exclude?: string | RegExp | (string | RegExp)[];
include?: string | RegExp | (string | RegExp)[];

Usage Examples:

// Exclude node_modules and specific directories
new ReactRefreshPlugin({
  exclude: [/node_modules/, /\.spec\.[jt]sx?$/]
});

// Include only specific file patterns
new ReactRefreshPlugin({
  include: /src\/.*\.[jt]sx?$/
});

// Multiple patterns
new ReactRefreshPlugin({
  exclude: [
    /node_modules/,
    /build/,
    path.resolve(__dirname, 'vendor')
  ]
});

Defaults:

  • exclude: /node_modules/
  • include: /\.([jt]sx?|flow)$/i

Library Option

Sets a namespace for the React Refresh runtime, useful when multiple instances run simultaneously.

library?: string;

Usage Examples:

// Set custom library namespace
new ReactRefreshPlugin({
  library: 'MyApp'
});

// Use webpack output configuration
module.exports = {
  output: {
    library: 'MyLibrary'
  },
  plugins: [
    new ReactRefreshPlugin() // Will use 'MyLibrary'
  ]
};

Default: '', or output.uniqueName in Webpack 5, or output.library if set

ES Module Options

Controls ES Modules compatibility for the refresh runtime.

esModule?: boolean | ESModuleOptions;

interface ESModuleOptions {
  /**
   * Files to explicitly exclude from flagged as ES Modules.
   */
  exclude?: string | RegExp | (string | RegExp)[];
  
  /**
   * Files to explicitly include for flagged as ES Modules.
   */
  include?: string | RegExp | (string | RegExp)[];
}

Usage Examples:

// Enable ES Modules globally
new ReactRefreshPlugin({
  esModule: true
});

// Granular ES Module control
new ReactRefreshPlugin({
  esModule: {
    include: /src\/.*\.m[jt]s$/,
    exclude: /legacy/
  }
});

// Auto-detection (default)
new ReactRefreshPlugin({
  esModule: undefined // Plugin will infer from package.json type or file extension
});

Default: undefined (auto-detection based on package.json type field or file extensions .mjs/.cjs)

Normalized Plugin Options

Internal interface representing processed plugin options after normalization.

interface NormalizedPluginOptions {
  esModule?: boolean | ESModuleOptions;
  exclude: string | RegExp | (string | RegExp)[];
  include: string | RegExp | (string | RegExp)[];
  forceEnable?: boolean;
  library?: string;
  overlay: false | NormalizedErrorOverlayOptions;
}

Options Validation

The plugin uses JSON schema validation to ensure correct configuration.

Schema Location: lib/options.json

Validation Features:

  • Type checking for all options
  • Pattern validation for file matching
  • Enum validation for overlay socket integration types
  • Additional properties prevention

Error Handling:

// Invalid configuration will throw during plugin instantiation
try {
  new ReactRefreshPlugin({
    invalidOption: true // Will throw validation error
  });
} catch (error) {
  console.error('Plugin configuration error:', error.message);
}

Install with Tessl CLI

npx tessl i tessl/npm-pmmmwh--react-refresh-webpack-plugin

docs

client-utilities.md

error-overlay.md

index.md

loader-configuration.md

plugin-configuration.md

plugin-utilities.md

runtime-utilities.md

socket-integrations.md

tile.json