0
# Build Status Management
1

2
Build event management system for communicating build status, errors, and fast refresh events through the overlay system.
3

4
## Capabilities
5

6
### Build Success Events
7

8
Signal successful build completion to the overlay system.
9

10
```typescript { .api }
11
/**
12
 * Emits a build success event to the overlay event bus
13
 * Typically called when webpack/turbopack compilation succeeds
14
 */
15
function onBuildOk(): void;
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { onBuildOk } from "@next/react-dev-overlay";
22

23
// Signal successful build
24
onBuildOk();
25

26
// In a webpack plugin or build system
27
class MyWebpackPlugin {
28
  apply(compiler) {
29
    compiler.hooks.done.tap('MyPlugin', (stats) => {
30
      if (!stats.hasErrors()) {
31
        onBuildOk();
32
      }
33
    });
34
  }
35
}
36
```
37

38
### Build Error Events
39

40
Signal build errors and failures to the overlay system with detailed error messages.
41

42
```typescript { .api }
43
/**
44
 * Emits a build error event to the overlay event bus
45
 * @param message - Error message describing the build failure
46
 */
47
function onBuildError(message: string): void;
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { onBuildError } from "@next/react-dev-overlay";
54

55
// Signal build error with message
56
onBuildError("TypeScript compilation failed: Type 'string' is not assignable to type 'number'");
57

58
// In a webpack plugin
59
class MyWebpackPlugin {
60
  apply(compiler) {
61
    compiler.hooks.done.tap('MyPlugin', (stats) => {
62
      if (stats.hasErrors()) {
63
        const errors = stats.toJson().errors;
64
        onBuildError(errors[0]?.message || 'Build failed');
65
      }
66
    });
67
  }
68
}
69

70
// With detailed error information
71
function handleCompilationError(error: Error) {
72
  onBuildError(`Compilation failed: ${error.message}\n\nStack: ${error.stack}`);
73
}
74
```
75

76
### Fast Refresh Events
77

78
Manage fast refresh lifecycle events for hot module replacement functionality.
79

80
```typescript { .api }
81
/**
82
 * Emits a refresh event indicating fast refresh is occurring
83
 * Used to coordinate UI updates during hot module replacement
84
 */
85
function onRefresh(): void;
86

87
/**
88
 * Emits a before refresh event to prepare for fast refresh
89
 * Allows cleanup or preparation before hot module replacement
90
 */
91
function onBeforeRefresh(): void;
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
import { onRefresh, onBeforeRefresh } from "@next/react-dev-overlay";
98

99
// Signal before refresh event
100
onBeforeRefresh();
101

102
// Perform refresh
103
onRefresh();
104

105
// In a hot module replacement context
106
if (module.hot) {
107
  module.hot.dispose(() => {
108
    onBeforeRefresh();
109
  });
110
  
111
  module.hot.accept(() => {
112
    onRefresh();
113
  });
114
}
115
```
116

117
### Event Bus Integration
118

119
The build status functions integrate with the internal event bus system that coordinates overlay behavior.
120

121
```typescript { .api }
122
// Event types used internally (exported constants)
123
const TYPE_BUILD_OK = 'build-ok';
124
const TYPE_BUILD_ERROR = 'build-error';
125
const TYPE_REFRESH = 'fast-refresh';
126
const TYPE_BEFORE_REFRESH = 'before-fast-refresh';
127
const TYPE_UNHANDLED_ERROR = 'unhandled-error';
128
const TYPE_UNHANDLED_REJECTION = 'unhandled-rejection';
129

130
interface BuildOk {
131
  type: typeof TYPE_BUILD_OK;
132
}
133

134
interface BuildError {
135
  type: typeof TYPE_BUILD_ERROR;
136
  message: string;
137
}
138

139
interface FastRefresh {
140
  type: typeof TYPE_REFRESH;
141
}
142

143
interface BeforeFastRefresh {
144
  type: typeof TYPE_BEFORE_REFRESH;
145
}
146

147
interface UnhandledError {
148
  type: typeof TYPE_UNHANDLED_ERROR;
149
  reason: Error;
150
  frames: StackFrame[];
151
  componentStack?: string[];
152
}
153

154
interface UnhandledRejection {
155
  type: typeof TYPE_UNHANDLED_REJECTION;
156
  reason: Error;
157
  frames: StackFrame[];
158
}
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
// These constants are used internally but can be useful for event filtering
165
import { TYPE_BUILD_OK, TYPE_BUILD_ERROR } from "@next/react-dev-overlay/internal/bus";
166

167
// Custom event handling (advanced usage)
168
function handleBuildEvents() {
169
  // The overlay system automatically handles these events
170
  // This is just to show the event structure
171
  const buildOkEvent: BuildOk = { type: TYPE_BUILD_OK };
172
  const buildErrorEvent: BuildError = { 
173
    type: TYPE_BUILD_ERROR, 
174
    message: "Build failed" 
175
  };
176
}
177
```
178

179
## Integration Patterns
180

181
### Webpack Integration
182

183
```typescript
184
// webpack.config.js or webpack plugin
185
const { onBuildOk, onBuildError } = require("@next/react-dev-overlay");
186

187
class OverlayPlugin {
188
  apply(compiler) {
189
    compiler.hooks.done.tap('OverlayPlugin', (stats) => {
190
      if (stats.hasErrors()) {
191
        const error = stats.toJson().errors[0];
192
        onBuildError(error?.message || 'Build failed');
193
      } else {
194
        onBuildOk();
195
      }
196
    });
197
  }
198
}
199
```
200

201
### Next.js Integration
202

203
```typescript
204
// next.config.js or Next.js plugin
205
const { onBuildOk, onBuildError, onRefresh, onBeforeRefresh } = require("@next/react-dev-overlay");
206

207
module.exports = {
208
  webpack(config, { dev, isServer }) {
209
    if (dev && !isServer) {
210
      // Add overlay integration
211
      config.plugins.push(
212
        new (class {
213
          apply(compiler) {
214
            compiler.hooks.done.tap('NextOverlay', (stats) => {
215
              if (stats.hasErrors()) {
216
                onBuildError('Next.js compilation failed');
217
              } else {
218
                onBuildOk();
219
              }
220
            });
221
          }
222
        })()
223
      );
224
    }
225
    return config;
226
  }
227
};
228
```