0
# Family & Instance Management
1

2
Advanced APIs for querying component families and finding affected DOM instances during refresh operations. Component families group related component versions together for efficient refresh decisions.
3

4
## Capabilities
5

6
### getFamilyByID
7

8
Retrieves a component family by its registration ID.
9

10
```javascript { .api }
11
/**
12
 * Retrieves component family by registration ID
13
 * @param id - Component registration ID used during register() call
14
 * @returns Family object if found, undefined otherwise
15
 * @throws Error if called in production environment
16
 */
17
function getFamilyByID(id: string): Family | void;
18
```
19

20
**Usage Example:**
21

22
```javascript
23
// After registering a component
24
ReactRefreshRuntime.register(MyComponent, 'MyComponent%default%');
25

26
// Later retrieve the family
27
const family = ReactRefreshRuntime.getFamilyByID('MyComponent%default%');
28
if (family) {
29
  console.log('Current component type:', family.current);
30
}
31
```
32

33
### getFamilyByType
34

35
Retrieves a component family by the component type itself.
36

37
```javascript { .api }
38
/**
39
 * Retrieves component family by component type
40
 * @param type - Component type (function or class)
41
 * @returns Family object if found, undefined otherwise
42
 * @throws Error if called in production environment
43
 */
44
function getFamilyByType(type: any): Family | void;
45
```
46

47
**Usage Example:**
48

49
```javascript
50
function MyComponent() {
51
  return <div>Hello</div>;
52
}
53

54
ReactRefreshRuntime.register(MyComponent, 'MyComponent');
55

56
// Retrieve family by component type
57
const family = ReactRefreshRuntime.getFamilyByType(MyComponent);
58
if (family) {
59
  console.log('Component is registered for refresh');
60
}
61
```
62

63
### findAffectedHostInstances
64

65
Finds all DOM instances that are affected by changes to the specified component families.
66

67
```javascript { .api }
68
/**
69
 * Finds DOM instances affected by component family changes
70
 * @param families - Array of component families to check
71
 * @returns Set of affected host DOM instances
72
 * @throws Error if called in production environment
73
 */
74
function findAffectedHostInstances(families: Array<Family>): Set<Instance>;
75
```
76

77
**Usage Example:**
78

79
```javascript
80
// Get families for components that changed
81
const family1 = ReactRefreshRuntime.getFamilyByID('Component1');
82
const family2 = ReactRefreshRuntime.getFamilyByID('Component2');
83

84
if (family1 && family2) {
85
  // Find affected DOM nodes
86
  const affectedInstances = ReactRefreshRuntime.findAffectedHostInstances([
87
    family1,
88
    family2
89
  ]);
90
  
91
  console.log(`${affectedInstances.size} DOM nodes will be affected`);
92
}
93
```
94

95
### isLikelyComponentType
96

97
Heuristic function to determine if a given type is likely a React component.
98

99
```javascript { .api }
100
/**
101
 * Heuristic to determine if type is likely a React component
102
 * @param type - Type to check (function, class, or object)
103
 * @returns True if type appears to be a React component
104
 * @throws Error if called in production environment
105
 */
106
function isLikelyComponentType(type: any): boolean;
107
```
108

109
**Usage Example:**
110

111
```javascript
112
function RegularFunction() {
113
  return "not a component";
114
}
115

116
function MyComponent() {
117
  return <div>Component</div>;
118
}
119

120
class MyClassComponent extends React.Component {
121
  render() {
122
    return <div>Class Component</div>;
123
  }
124
}
125

126
// Check component likelihood
127
console.log(ReactRefreshRuntime.isLikelyComponentType(RegularFunction)); // false
128
console.log(ReactRefreshRuntime.isLikelyComponentType(MyComponent)); // true
129
console.log(ReactRefreshRuntime.isLikelyComponentType(MyClassComponent)); // true
130
```
131

132
## Component Family Lifecycle
133

134
Understanding how component families work:
135

136
### Family Creation
137

138
```javascript
139
// First registration creates a new family
140
ReactRefreshRuntime.register(MyComponentV1, 'MyComponent');
141

142
const family = ReactRefreshRuntime.getFamilyByID('MyComponent');
143
console.log(family.current === MyComponentV1); // true
144
```
145

146
### Family Updates
147

148
```javascript
149
// Later registration with same ID updates the family
150
ReactRefreshRuntime.register(MyComponentV2, 'MyComponent');
151

152
// Family now points to new version
153
const updatedFamily = ReactRefreshRuntime.getFamilyByID('MyComponent');
154
console.log(updatedFamily.current === MyComponentV2); // true
155

156
// This triggers a pending update for the next refresh cycle
157
```
158

159
### Refresh Decisions
160

161
```javascript
162
// During performReactRefresh(), families are categorized:
163
const refreshResult = ReactRefreshRuntime.performReactRefresh();
164

165
// Components that can preserve state
166
refreshResult.updatedFamilies.forEach(family => {
167
  console.log('Fast refresh:', family.current.name);
168
});
169

170
// Components that must remount
171
refreshResult.staleFamilies.forEach(family => {
172
  console.log('Full refresh:', family.current.name);
173
});
174
```
175

176
## Types
177

178
```javascript { .api }
179
interface Family {
180
  /** Current component type in this family */
181
  current: any;
182
}
183

184
/** React host instance (DOM node in browsers) */
185
type Instance = any;
186
```
187

188
## Integration Notes
189

190
- Families are created automatically during component registration
191
- Multiple component versions can belong to the same family
192
- Family queries are fast lookups using WeakMap/Map structures
193
- Host instance finding traverses the React fiber tree
194
- These APIs are primarily used by development tools and advanced integrations