Development Server Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Development Server Setup for the Promethean Conduit project is a sophisticated middleware configuration built on top of webpack-dev-server. It extends the standard development environment by integrating advanced features such as live visual editing of React components, real-time health monitoring, and secure AST-based file modification. This setup is primarily managed through craco (Create React App Configuration Override) to allow for custom Babel and Webpack configurations without ejecting.
Sources: frontend/craco.config.js:1-15, frontend/plugins/visual-edits/dev-server-setup.js:1-10
Middleware Architecture
The development server architecture utilizes a conditional loading mechanism based on environment variables defined in .env. The configuration supports two primary plugin systems: Visual Edits and Health Check. These plugins hook into the setupMiddlewares lifecycle of the Webpack dev server to expose specialized API endpoints.
The server identifies the developer environment and selectively activates features like hot reload disabling or specialized file watching patterns to optimize performance.
Sources: frontend/craco.config.js:20-55, frontend/plugins/visual-edits/dev-server-setup.js:40-45
Visual Editing System
The Visual Editing system allows developers to modify React components directly through the UI. It combines a Babel plugin that injects metadata into JSX elements with a dev server middleware that handles the physical file writes using Abstract Syntax Trees (AST).
Babel Metadata Injection
The babel-metadata-plugin.js scans JSX code during the build process and injects attributes such as x-file-name, x-line-number, and x-id. This allows the frontend to uniquely identify the source code location of any rendered element.
Sources: frontend/plugins/visual-edits/babel-metadata-plugin.js:460-500
Secure File Modification
The /edit-file endpoint receives change requests, validates them against an authorized origin, and checks for a x-api-key retrieved from the local Supervisor configuration. It uses @babel/parser and @babel/traverse to locate the exact line and element in the source code before applying updates.
Health Monitoring Endpoints
The development server includes a health check suite that provides real-time statistics about the Webpack compilation state and host system resources. These are configured in health-endpoints.js.
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Comprehensive JSON object containing Webpack state, uptime, and memory usage. |
/health/simple | GET | Returns plain text status: OK, COMPILING, or ERROR. |
/health/ready | GET | Readiness check for load balancers or Kubernetes probes. |
/health/live | GET | Liveness check confirming the Node.js process is responsive. |
/health/stats | GET | Compilation metrics including average compile time and total counts. |
Sources: frontend/plugins/health-check/health-endpoints.js:26-110
Configuration and Environment
The dev server behavior is governed by environment variables and the craco.config.js file.
| Variable | Type | Default | Description |
|---|---|---|---|
DISABLE_HOT_RELOAD | Boolean | false | When true, removes HotModuleReplacementPlugin and stops file watching. |
REACT_APP_ENABLE_VISUAL_EDITS | Boolean | false | Enables the Babel metadata plugin and /edit-file endpoint. |
ENABLE_HEALTH_CHECK | Boolean | false | Activates the WebpackHealthPlugin and health API endpoints. |
PORT | Integer | 3000 | Standard React development port. |
Sources: frontend/craco.config.js:5-15, frontend/package.json:90-95
File Watcher Optimization
To maintain performance during development, the server is configured to ignore heavy directories. This is handled in the webpackConfig.watchOptions configuration within craco.config.js. Excluded patterns include node_modules, .git, build, dist, coverage, and public.
Sources: frontend/craco.config.js:54-65
Security Protocols
The development server setup implements several security measures to prevent unauthorized file access or modification:
- Origin Validation: The server checks the
Originheader against a whitelist of allowed domains, includinglocalhost,127.0.0.1, and subdomains ofemergent.shandemergentagent.com. - API Key Verification: Requests to sensitive endpoints must include an
x-api-keythat matches thePASSWORDfound in/etc/supervisor/conf.d/supervisord_code_server.conf. - Path Traversal Protection: The file editing logic uses
path.normalizeand ensures the target file resides strictly within the frontend root directory. - Restricted Directories: Modifications to
node_modulesorpublicdirectories are explicitly forbidden through hardcoded path checks.
Sources: frontend/plugins/visual-edits/dev-server-setup.js:15-38, frontend/plugins/visual-edits/dev-server-setup.js:125-145
The Development Server Setup provides a robust foundation for building and maintaining the Promethean Conduit, offering unique tools for visual editing while maintaining rigorous security and monitoring standards.