Health Check Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The Health Check Plugin is a specialized monitoring system designed to track the compilation state, system resource usage, and overall health of the frontend application. It integrates directly with the Webpack build process and the development server to provide real-time metrics and diagnostic endpoints suitable for both development troubleshooting and production orchestration tools like Kubernetes.
The system is composed of a custom Webpack plugin that hooks into compiler lifecycles and a set of Express-compatible middleware endpoints. It captures detailed statistics including compile durations, error/warning counts, and system-level metrics such as memory usage and uptime.
Sources: frontend/plugins/health-check/webpack-health-plugin.js:4-20, frontend/plugins/health-check/health-endpoints.js:14-25, frontend/craco.config.js:23-28
Architecture and Components
The health check system operates through three primary layers: the Webpack instrumentation layer, the data aggregation layer, and the API presentation layer.
Webpack Integration
The WebpackHealthPlugin class monitors the Webpack compiler hooks. It tracks four distinct states: idle, compiling, success, and failed. It taps into compile, done, failed, and invalid hooks to update internal state metrics.
The plugin maintains a persistent status object containing error arrays, timestamps for the first and last compilations, and cumulative counters.
Sources: frontend/plugins/health-check/webpack-health-plugin.js:23-88
API Endpoints
The setupHealthEndpoints function registers several routes on the Webpack Dev Server (or any Express app) to expose the collected data.
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Returns comprehensive JSON including Webpack status, server info, and memory usage. |
/health/simple | GET | Returns plain text status: OK, COMPILING, IDLE, or ERROR (503). |
/health/ready | GET | Readiness check for load balancers; returns 200 only if state is success. |
/health/live | GET | Liveness check; returns 200 and a timestamp to confirm the process is running. |
/health/errors | GET | Detailed breakdown of current compilation errors and warnings. |
/health/stats | GET | Compilation performance statistics including average compile time. |
Sources: frontend/plugins/health-check/health-endpoints.js:33-145
Data Flow and Logic
When a file change occurs, Webpack triggers the invalid hook. The plugin updates the state to compiling. Once finished, the done hook provides a stats object, which the plugin parses into a simplified error/warning format.
System metrics are retrieved dynamically during the request using the Node.js os and process modules, ensuring that memory usage and CPU info are current at the time of the query.
Sources: frontend/plugins/health-check/webpack-health-plugin.js:46-88, frontend/plugins/health-check/health-endpoints.js:34-75
Configuration and Activation
The plugin is conditionally loaded via craco.config.js based on environment variables. This ensures that health monitoring overhead is only present when explicitly requested.
Environment Variables
| Variable | Type | Default | Description |
|---|---|---|---|
ENABLE_HEALTH_CHECK | Boolean | false | Enables the plugin and its endpoints. |
Registration Logic
The plugin is instantiated and added to the Webpack plugins array. The endpoints are injected into the devServer.setupMiddlewares chain.
// craco.config.js integration
if (config.enableHealthCheck) {
WebpackHealthPlugin = require("./plugins/health-check/webpack-health-plugin");
setupHealthEndpoints = require("./plugins/health-check/health-endpoints");
healthPluginInstance = new WebpackHealthPlugin();
}
// Inside webpackConfig.plugins.push
if (config.enableHealthCheck && healthPluginInstance) {
webpackConfig.plugins.push(healthPluginInstance);
}
Sources: frontend/craco.config.js:8-10, frontend/craco.config.js:23-28, frontend/craco.config.js:84-111, DEPLOYMENT_GUIDE.md:200-205
Implementation Details
Status Data Structure
The internal state managed by the plugin follows this schema:
this.status = {
state: 'idle', // idle, compiling, success, failed
errors: [], // {message, stack, moduleName, loc}
warnings: [], // {message, moduleName, loc}
lastCompileTime: null, // epoch ms
lastSuccessTime: null, // epoch ms
compileDuration: 0, // ms
totalCompiles: 0, // counter
firstCompileTime: null // epoch ms
};
Sources: frontend/plugins/health-check/webpack-health-plugin.js:6-16, frontend/plugins/health-check/webpack-health-plugin.js:58-63
Formatter Helpers
The health-endpoints.js file includes utility functions to convert raw system bytes and durations into human-readable strings (e.g., formatBytes for MB/GB and formatDuration for h/m/s).
Sources: frontend/plugins/health-check/health-endpoints.js:154-188
Summary
The Health Check Plugin provides a robust observability layer for the frontend development and deployment lifecycle. By bridging Webpack's internal state with accessible HTTP endpoints, it allows for automated readiness/liveness probing and detailed performance auditing of the build system.