tessl/npm-react-refresh

React Refresh runtime and Babel plugin for Fast Refresh functionality that enables live editing of React components without losing state

—

Pending

Overview

Eval results

Files

Babel Plugin

Name: tessl/npm-react-refresh
Author: tessl

Babel transformation plugin that automatically instruments React components for Fast Refresh support. The plugin analyzes component code and injects the necessary registration and signature calls.

Capabilities

BabelPlugin

Main plugin factory function that creates the Babel plugin configuration.

/**
 * Babel plugin factory for React Refresh transforms
 * @param babel - Babel instance with types and utilities
 * @param opts - Plugin configuration options
 * @returns Babel plugin configuration object
 * @throws Error if not in development environment (unless skipEnvCheck is true)
 */
function BabelPlugin(babel: any, opts?: BabelPluginOptions): BabelPluginConfig;

interface BabelPluginOptions {
  /** Custom refresh registration function name (default: '$RefreshReg$') */
  refreshReg?: string;
  /** Custom refresh signature function name (default: '$RefreshSig$') */
  refreshSig?: string;
  /** Skip development environment check */
  skipEnvCheck?: boolean;
  /** Emit full signatures instead of hashed keys */
  emitFullSignatures?: boolean;
}

interface BabelPluginConfig {
  visitor: {
    ExportDefaultDeclaration: Function;
    FunctionDeclaration: Function;
    VariableDeclaration: Function;
    Program: Function;
    [key: string]: any;
  };
}

Usage Example:

// babel.config.js
module.exports = {
  plugins: [
    ['react-refresh/babel', {
      skipEnvCheck: process.env.NODE_ENV !== 'development',
      refreshReg: '$RefreshReg$',
      refreshSig: '$RefreshSig$',
      emitFullSignatures: false
    }]
  ]
};

Plugin Options

refreshReg

Customize the registration function name used in generated code:

// With default options
$RefreshReg$(MyComponent, 'MyComponent');

// With custom refreshReg: 'myCustomReg'
myCustomReg(MyComponent, 'MyComponent');

refreshSig

Customize the signature function name used in generated code:

// With default options
$RefreshSig$(MyComponent, 'hookSignature', false);

// With custom refreshSig: 'myCustomSig'
myCustomSig(MyComponent, 'hookSignature', false);

skipEnvCheck

Skip the automatic development environment check:

// Plugin normally throws in production unless skipEnvCheck is true
{
  plugins: [
    ['react-refresh/babel', { skipEnvCheck: true }]
  ]
}

emitFullSignatures

Control signature key format:

// With emitFullSignatures: false (default)
$RefreshSig$(MyComponent, 'a8f3k2n9x7', false);

// With emitFullSignatures: true
$RefreshSig$(MyComponent, 'useState{[count, setCount]}(0)', false);

Code Transformations

The plugin performs several AST transformations:

Function Components

Input:

function MyComponent() {
  const [count, setCount] = useState(0);
  return <div>{count}</div>;
}

Output:

var _s = $RefreshSig$();

function MyComponent() {
  _s();
  const [count, setCount] = useState(0);
  return <div>{count}</div>;
}

_s(MyComponent, 'useState{[count, setCount]}(0)', false);

Arrow Function Components

Input:

const MyComponent = () => {
  const [count, setCount] = useState(0);
  return <div>{count}</div>;
};

Output:

var _s = $RefreshSig$();

const MyComponent = () => {
  _s();
  const [count, setCount] = useState(0);
  return <div>{count}</div>;
};

_s(MyComponent, 'useState{[count, setCount]}(0)', false);

Export Default Components

Input:

export default function MyComponent() {
  return <div>Hello</div>;
}

Output:

var _c;

export default function MyComponent() {
  return <div>Hello</div>;
}

_c = MyComponent;
$RefreshReg$(_c, 'MyComponent%default%');

Higher-Order Components

Input:

const EnhancedComponent = memo(() => {
  return <div>Enhanced</div>;
});

Output:

var _s = $RefreshSig$();
var _c;

const EnhancedComponent = _c = memo(_s(() => {
  _s();
  return <div>Enhanced</div>;
}, 'hookSignature'));

$RefreshReg$(_c, 'EnhancedComponent');

Hook Signature Detection

The plugin automatically detects Hook usage patterns:

Built-in Hooks

useState, useReducer, useEffect, useLayoutEffect
useMemo, useCallback, useRef, useContext
useImperativeMethods, useDebugValue

Custom Hooks

Any function call starting with use and a capital letter:

function MyComponent() {
  const data = useCustomData();
  const auth = useAuth();
  // etc.
}

Signature Generation

// Single Hook
'useState{[count, setCount]}(0)'

// Multiple Hooks
'useState{[count, setCount]}(0)\nuseEffect{}([count])'

// Custom Hooks
'useCustomHook{}'

Force Reset Comments

Use special comments to force component remounting:

/* @refresh reset */

function MyComponent() {
  // This component will always remount on changes
  return <div>Always resets</div>;
}

Environment Detection

The plugin automatically detects the environment:

// Automatically enabled in development
babel.env() === 'development'

// Throws error in production unless skipEnvCheck: true
babel.env() === 'production' // Error!