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
```