0
# Runtime API
1

2
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.
3

4
## Capabilities
5

6
### performReactRefresh
7

8
Performs a React component refresh cycle, processing all pending component updates and determining which components need re-rendering vs remounting.
9

10
```javascript { .api }
11
/**
12
 * Performs React component refresh cycle
13
 * @returns RefreshUpdate object with family information, or null if no updates pending
14
 * @throws Error if called in production environment
15
 */
16
function performReactRefresh(): RefreshUpdate | null;
17

18
interface RefreshUpdate {
19
  /** Families that will re-render while preserving state */
20
  updatedFamilies: Set<Family>;
21
  /** Families that will be remounted (losing state) */
22
  staleFamilies: Set<Family>;
23
}
24
```
25

26
**Usage Example:**
27

28
```javascript
29
import * as ReactRefreshRuntime from 'react-refresh/runtime';
30

31
// After component code changes, trigger refresh
32
const refreshResult = ReactRefreshRuntime.performReactRefresh();
33

34
if (refreshResult) {
35
  console.log(`Updated ${refreshResult.updatedFamilies.size} families`);
36
  console.log(`Remounted ${refreshResult.staleFamilies.size} families`);
37
}
38
```
39

40
### register
41

42
Registers a React component type with a unique identifier for refresh tracking. This creates or updates component families used to determine refresh behavior.
43

44
```javascript { .api }
45
/**
46
 * Registers a React component type for refresh tracking
47
 * @param type - Component function or class to register
48
 * @param id - Unique string identifier for the component
49
 * @throws Error if called in production environment
50
 */
51
function register(type: any, id: string): void;
52
```
53

54
**Usage Example:**
55

56
```javascript
57
function MyComponent() {
58
  const [count, setCount] = React.useState(0);
59
  return <div>{count}</div>;
60
}
61

62
// Register component with unique ID
63
ReactRefreshRuntime.register(MyComponent, 'MyComponent%default%');
64

65
// For multiple components in same file
66
ReactRefreshRuntime.register(AnotherComponent, 'AnotherComponent');
67
```
68

69
### injectIntoGlobalHook
70

71
Injects React Refresh runtime into the React DevTools global hook, enabling communication with React renderers.
72

73
```javascript { .api }
74
/**
75
 * Injects React Refresh runtime into React DevTools global hook
76
 * @param globalObject - Global object (window in browsers, global in Node.js)
77
 * @throws Error if called in production environment
78
 */
79
function injectIntoGlobalHook(globalObject: any): void;
80
```
81

82
**Usage Example:**
83

84
```javascript
85
import * as ReactRefreshRuntime from 'react-refresh/runtime';
86

87
// Browser setup
88
ReactRefreshRuntime.injectIntoGlobalHook(window);
89

90
// Node.js setup
91
ReactRefreshRuntime.injectIntoGlobalHook(global);
92
```
93

94
### hasUnrecoverableErrors
95

96
Checks for unrecoverable errors in the refresh system. Currently always returns false but maintained for compatibility.
97

98
```javascript { .api }
99
/**
100
 * Checks for unrecoverable errors in refresh system
101
 * @returns Always returns false in current implementation
102
 * @throws Error if called in production environment
103
 */
104
function hasUnrecoverableErrors(): boolean;
105
```
106

107
### _getMountedRootCount
108

109
Returns the count of currently mounted React roots. This is a testing utility and should not be used in production code.
110

111
```javascript { .api }
112
/**
113
 * Returns count of mounted React roots (testing utility)
114
 * @returns Number of mounted roots
115
 * @throws Error if called in production environment
116
 */
117
function _getMountedRootCount(): number;
118
```
119

120
## Error Handling
121

122
All React Refresh runtime functions throw errors when called in production environments:
123

124
```javascript
125
// Will throw: "Unexpected call to React Refresh in a production environment."
126
ReactRefreshRuntime.performReactRefresh();
127
```
128

129
The runtime automatically detects production vs development environments and prevents accidental usage in production builds.
130

131
## Integration Notes
132

133
- Call `injectIntoGlobalHook()` before React initializes
134
- Register components immediately after definition
135
- Call `performReactRefresh()` after code changes are applied
136
- Runtime maintains internal state between refresh cycles