0
# React Refresh
1

2
React Refresh provides the runtime and Babel plugin necessary to integrate Fast Refresh functionality into bundlers. Fast Refresh enables developers to edit React components in a running application without losing component state, offering a superior alternative to traditional hot reloading with official React team support.
3

4
## Package Information
5

6
- **Package Name**: react-refresh
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: `npm install react-refresh`
10

11
## Core Imports
12

13
Runtime API:
14

15
```javascript
16
import * as ReactRefreshRuntime from 'react-refresh/runtime';
17
```
18

19
For CommonJS:
20

21
```javascript
22
const ReactRefreshRuntime = require('react-refresh/runtime');
23
```
24

25
Babel Plugin:
26

27
```javascript
28
// babel.config.js
29
{
30
  plugins: [
31
    ['react-refresh/babel', options]
32
  ]
33
}
34
```
35

36
## Basic Usage
37

38
### Runtime Setup
39

40
```javascript
41
import * as ReactRefreshRuntime from 'react-refresh/runtime';
42

43
// Initialize React Refresh
44
ReactRefreshRuntime.injectIntoGlobalHook(window);
45

46
// Register a component
47
function MyComponent() {
48
  const [count, setCount] = React.useState(0);
49
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
50
}
51

52
// Register the component for refresh tracking
53
ReactRefreshRuntime.register(MyComponent, 'MyComponent');
54

55
// Perform refresh after code changes
56
ReactRefreshRuntime.performReactRefresh();
57
```
58

59
### Babel Plugin Setup
60

61
```javascript
62
// babel.config.js
63
module.exports = {
64
  plugins: [
65
    ['react-refresh/babel', {
66
      skipEnvCheck: true, // Skip environment check if needed
67
      refreshReg: '$RefreshReg$', // Custom registration function name
68
      refreshSig: '$RefreshSig$'  // Custom signature function name
69
    }]
70
  ]
71
};
72
```
73

74
## Architecture
75

76
React Refresh is built around several key components:
77

78
- **Runtime System**: Core refresh logic managing component families, signatures, and state preservation
79
- **Component Registration**: Tracking system that assigns unique IDs to components for refresh decisions
80
- **Hook Signatures**: System for detecting Hook usage changes to determine if state can be preserved
81
- **Babel Transform**: Code instrumentation that automatically adds refresh support during compilation
82
- **DevTools Integration**: Hooks into React DevTools infrastructure for renderer communication
83

84
## Capabilities
85

86
### Runtime API
87

88
Core runtime functionality for managing Fast Refresh state and performing component updates. Essential for bundler integrations and development servers.
89

90
```javascript { .api }
91
function performReactRefresh(): RefreshUpdate | null;
92
function register(type: any, id: string): void;
93
function injectIntoGlobalHook(globalObject: any): void;
94
```
95

96
[Runtime API](./runtime.md)
97

98
### Component Registration & Signatures
99

100
System for tracking components and their Hook usage patterns to enable intelligent refresh decisions.
101

102
```javascript { .api }
103
function setSignature(
104
  type: any, 
105
  key: string, 
106
  forceReset?: boolean, 
107
  getCustomHooks?: () => Array<Function>
108
): void;
109

110
function collectCustomHooksForSignature(type: any): void;
111
function createSignatureFunctionForTransform(): Function;
112
```
113

114
[Registration & Signatures](./registration.md)
115

116
### Family & Instance Management
117

118
Advanced APIs for querying component families and finding affected DOM instances during refresh operations.
119

120
```javascript { .api }
121
function getFamilyByID(id: string): Family | void;
122
function getFamilyByType(type: any): Family | void;
123
function findAffectedHostInstances(families: Array<Family>): Set<Instance>;
124
```
125

126
[Family Management](./families.md)
127

128
### Babel Plugin
129

130
Babel transformation plugin that automatically instruments React components for Fast Refresh support.
131

132
```javascript { .api }
133
function BabelPlugin(babel: any, opts?: BabelPluginOptions): BabelPluginConfig;
134

135
interface BabelPluginOptions {
136
  refreshReg?: string;
137
  refreshSig?: string;
138
  skipEnvCheck?: boolean;
139
  emitFullSignatures?: boolean;
140
}
141
```
142

143
[Babel Plugin](./babel-plugin.md)
144

145
## Types
146

147
```javascript { .api }
148
interface RefreshUpdate {
149
  updatedFamilies: Set<Family>;
150
  staleFamilies: Set<Family>;
151
}
152

153
interface Family {
154
  current: any;
155
}
156

157
interface Signature {
158
  ownKey: string;
159
  forceReset: boolean;
160
  fullKey: string | null;
161
  getCustomHooks: () => Array<Function>;
162
}
163
```