tessl/npm-react-refresh
React Refresh runtime and Babel plugin for Fast Refresh functionality that enables live editing of React components without losing state
—
runtime.mddocs/
Runtime API
Core runtime functionality for managing Fast Refresh state and performing component updates. These functions are essential for bundler integrations and development servers implementing Fast Refresh support.
Capabilities
performReactRefresh
Performs a React component refresh cycle, processing all pending component updates and determining which components need re-rendering vs remounting.
/**
* Performs React component refresh cycle
* @returns RefreshUpdate object with family information, or null if no updates pending
* @throws Error if called in production environment
*/
function performReactRefresh(): RefreshUpdate | null;
interface RefreshUpdate {
/** Families that will re-render while preserving state */
updatedFamilies: Set<Family>;
/** Families that will be remounted (losing state) */
staleFamilies: Set<Family>;
}Usage Example:
import * as ReactRefreshRuntime from 'react-refresh/runtime';
// After component code changes, trigger refresh
const refreshResult = ReactRefreshRuntime.performReactRefresh();
if (refreshResult) {
console.log(`Updated ${refreshResult.updatedFamilies.size} families`);
console.log(`Remounted ${refreshResult.staleFamilies.size} families`);
}register
Registers a React component type with a unique identifier for refresh tracking. This creates or updates component families used to determine refresh behavior.
/**
* Registers a React component type for refresh tracking
* @param type - Component function or class to register
* @param id - Unique string identifier for the component
* @throws Error if called in production environment
*/
function register(type: any, id: string): void;Usage Example:
function MyComponent() {
const [count, setCount] = React.useState(0);
return <div>{count}</div>;
}
// Register component with unique ID
ReactRefreshRuntime.register(MyComponent, 'MyComponent%default%');
// For multiple components in same file
ReactRefreshRuntime.register(AnotherComponent, 'AnotherComponent');injectIntoGlobalHook
Injects React Refresh runtime into the React DevTools global hook, enabling communication with React renderers.
/**
* Injects React Refresh runtime into React DevTools global hook
* @param globalObject - Global object (window in browsers, global in Node.js)
* @throws Error if called in production environment
*/
function injectIntoGlobalHook(globalObject: any): void;Usage Example:
import * as ReactRefreshRuntime from 'react-refresh/runtime';
// Browser setup
ReactRefreshRuntime.injectIntoGlobalHook(window);
// Node.js setup
ReactRefreshRuntime.injectIntoGlobalHook(global);hasUnrecoverableErrors
Checks for unrecoverable errors in the refresh system. Currently always returns false but maintained for compatibility.
/**
* Checks for unrecoverable errors in refresh system
* @returns Always returns false in current implementation
* @throws Error if called in production environment
*/
function hasUnrecoverableErrors(): boolean;_getMountedRootCount
Returns the count of currently mounted React roots. This is a testing utility and should not be used in production code.
/**
* Returns count of mounted React roots (testing utility)
* @returns Number of mounted roots
* @throws Error if called in production environment
*/
function _getMountedRootCount(): number;Error Handling
All React Refresh runtime functions throw errors when called in production environments:
// Will throw: "Unexpected call to React Refresh in a production environment."
ReactRefreshRuntime.performReactRefresh();The runtime automatically detects production vs development environments and prevents accidental usage in production builds.
Integration Notes
- Call
injectIntoGlobalHook()before React initializes - Register components immediately after definition
- Call
performReactRefresh()after code changes are applied - Runtime maintains internal state between refresh cycles
Install with Tessl CLI
npx tessl i tessl/npm-react-refresh