CRACO Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The CRACO (Create React App Configuration Override) configuration in the EVI3_0 project serves as a sophisticated orchestration layer that extends the standard Create React App build pipeline. It provides a modular system for conditionally injecting development tools, performance optimizations, and specialized middleware without ejecting from the underlying framework.
This configuration is central to the project's development workflow, enabling advanced features such as an Abstract Syntax Tree (AST) based visual editing system, a comprehensive health monitoring API for the Webpack Dev Server, and customized build-time path aliasing.
Core Configuration Logic
The configuration is driven by environment variables defined in .env files. It dynamically imports and initializes specific plugins based on the current environment state.
Environment Overrides
The system evaluates three primary flags to determine the configuration profile:
- disableHotReload: When set to
true, it removes theHotModuleReplacementPluginand setswatchmode to false, effectively freezing the build state. - enableVisualEdits: Triggers the inclusion of the
babel-metadata-pluginand specialized Dev Server endpoints for file manipulation. - enableHealthCheck: Activates the
WebpackHealthPluginand exposes internal monitoring endpoints like/healthand/health/stats.
Sources: frontend/craco.config.js:6-10, frontend/craco.config.js:41-51
Webpack and Babel Extensions
CRACO is used to inject custom logic into the Webpack bundling process and the Babel transformation pipeline.
Path Aliasing
A global alias @ is resolved to the src directory, allowing for cleaner imports across the frontend codebase.
Sources: frontend/craco.config.js:34-36
Visual Editing Pipeline
When enableVisualEdits is active, a custom Babel plugin is injected into the transformation chain. This plugin, babel-metadata-plugin.js, performs the following:
- AST Transformation: Scans JSX elements during build time.
- Metadata Injection: Stamps elements with technical metadata including
x-file-name,x-line-number, andx-id. - Dynamic Analysis: Determines if a component is "dynamic" (e.g., inside a
.map()call) to prevent dangerous edits.
Sources: frontend/plugins/visual-edits/babel-metadata-plugin.js:460-520, frontend/craco.config.js:84-88
Health Monitoring Infrastructure
The health check system integrates a custom Webpack plugin that tracks the status of the compilation process.
| Feature | Description | Source |
|---|---|---|
| Status Tracking | Monitors if Webpack is in 'success', 'compiling', or 'error' state. | frontend/plugins/health-check/health-endpoints.js:35-45 |
| Performance Metrics | Calculates total compile counts and average compile durations. | frontend/plugins/health-check/health-endpoints.js:142-155 |
| System Visibility | Reports Node.js version, platform, and memory usage (Heap, RSS). | frontend/plugins/health-check/health-endpoints.js:63-80 |
Dev Server Middleware Integration
The devServer configuration block in craco.config.js is used to extend the Express.js server that powers the development environment.
Visual Edit Endpoint (/edit-file)
This endpoint allows for programmatic modification of source files. It includes strict security checks:
- CORS Validation: Only allows specific origins like
localhostoremergentagent.com. - API Key Protection: Requires a header
x-api-keymatching the system's Supervisor password. - Path Traversal Protection: Ensures target files are within the frontend root and excludes
node_modulesorbuilddirectories.
Sources: frontend/plugins/visual-edits/dev-server-setup.js:52-110
Health Endpoints
The configuration exposes several standardized endpoints for monitoring:
/health: Full diagnostic report./health/simple: ReturnsOK,COMPILING, orERRORfor basic uptime checks./health/ready: A readiness probe for load balancers./health/live: A liveness probe confirming the server is alive.
Sources: frontend/plugins/health-check/health-endpoints.js:159-165
Dependency Configuration
The configuration relies on several key packages defined in the project's dependency manifest.
| Dependency | Purpose | Source |
|---|---|---|
@craco/craco | The core override framework. | frontend/package.json:100 |
tailwindcss | Integrated via PostCSS configuration. | frontend/package.json:107 |
dotenv | Used within the config to load environment-specific flags. | frontend/craco.config.js:3 |
path | Node.js module for directory resolution. | frontend/craco.config.js:2 |
Sources: frontend/package.json:99-108, frontend/craco.config.js:2-3
Summary
The CRACO configuration in EVI3_0 is a vital architectural component that transforms a standard React setup into a highly manageable and extensible development platform. By leveraging Babel AST transformations and Webpack Dev Server middleware, it facilitates a robust "visual editing" experience and provides enterprise-grade health monitoring, all while maintaining strict security boundaries and environment-based flexibility.
Sources: frontend/craco.config.js, frontend/plugins/visual-edits/dev-server-setup.js, frontend/plugins/health-check/health-endpoints.js