mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-25 06:14:59 +00:00
johndoe6345789
a51130a127
- codegen: Low-code React app with JSON-driven component system - packagerepo: Schema-driven package repository with backend/frontend - postgres: Next.js app with Drizzle ORM and PostgreSQL Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
486 lines
9.5 KiB
Markdown
486 lines
9.5 KiB
Markdown
# JSON Configuration Quick Reference
|
|
|
|
## 📚 Configuration Files Overview
|
|
|
|
CodeForge now uses JSON configuration files for all major settings. This guide shows what each file contains and how to use them.
|
|
|
|
---
|
|
|
|
## 📄 File Locations
|
|
|
|
```
|
|
/workspaces/spark-template/
|
|
├── app.config.json # Main application configuration
|
|
├── component-registry.json # Component lazy loading definitions
|
|
├── feature-toggles.json # Feature flag defaults and profiles
|
|
├── deployment-config.json # Platform-specific deployment settings
|
|
├── theme.json # Tailwind theme customization (empty but supported)
|
|
├── components.json # shadcn component configuration
|
|
├── architecture.json # Architecture and page renderer config
|
|
└── src/config/
|
|
├── pages.json # Page definitions and navigation
|
|
├── seed-data.json # Default project data
|
|
└── component-trees/ # JSON component tree definitions
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 app.config.json
|
|
|
|
**Purpose:** Main application settings including branding, server, build, and features
|
|
|
|
### Key Sections:
|
|
|
|
#### App Metadata
|
|
```json
|
|
{
|
|
"app": {
|
|
"name": "CodeForge",
|
|
"title": "CodeForge - Low-Code Development Platform",
|
|
"version": "6.0.0",
|
|
"themeColor": "#8b5cf6"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Server Configuration
|
|
```json
|
|
{
|
|
"server": {
|
|
"development": {
|
|
"host": "0.0.0.0",
|
|
"port": 5000
|
|
},
|
|
"production": {
|
|
"host": "0.0.0.0",
|
|
"port": 80,
|
|
"basePath": "./"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Build Settings
|
|
```json
|
|
{
|
|
"build": {
|
|
"outDir": "dist",
|
|
"sourcemap": false,
|
|
"minify": "terser",
|
|
"chunks": {
|
|
"react-vendor": ["react", "react-dom"],
|
|
"ui-core": ["@radix-ui/..."]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Feature Flags
|
|
```json
|
|
{
|
|
"features": {
|
|
"preloadCriticalComponents": true,
|
|
"bundleMetrics": true
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🎨 component-registry.json
|
|
|
|
**Purpose:** Define all lazy-loaded components with preload strategies
|
|
|
|
### Structure:
|
|
|
|
```json
|
|
{
|
|
"components": [
|
|
{
|
|
"name": "ProjectDashboard",
|
|
"path": "@/components/ProjectDashboard",
|
|
"export": "ProjectDashboard",
|
|
"type": "feature",
|
|
"preload": true,
|
|
"preloadPriority": "high",
|
|
"category": "dashboard"
|
|
}
|
|
],
|
|
"dialogs": [...],
|
|
"pwa": [...],
|
|
"preloadStrategy": {
|
|
"critical": ["ProjectDashboard", "CodeEditor"],
|
|
"preloadDelay": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
### Component Properties:
|
|
|
|
- `name` - Unique component identifier
|
|
- `path` - Import path
|
|
- `export` - Named export from module
|
|
- `type` - Component type (feature, dialog, pwa)
|
|
- `preload` - Whether to preload component
|
|
- `preloadPriority` - Priority level (high, medium, low)
|
|
- `category` - Grouping category
|
|
- `dependencies` - External dependencies (e.g., monaco-editor)
|
|
- `experimental` - Mark as experimental feature
|
|
|
|
---
|
|
|
|
## 🎛️ feature-toggles.json
|
|
|
|
**Purpose:** Feature flag defaults, profiles, and environment overrides
|
|
|
|
### Structure:
|
|
|
|
```json
|
|
{
|
|
"defaults": {
|
|
"codeEditor": {
|
|
"enabled": true,
|
|
"description": "Monaco code editor...",
|
|
"category": "core"
|
|
}
|
|
},
|
|
"categories": {
|
|
"core": {
|
|
"label": "Core Features",
|
|
"icon": "StarFour"
|
|
}
|
|
},
|
|
"environments": {
|
|
"development": {
|
|
"overrides": {
|
|
"modelsJSON": true
|
|
}
|
|
}
|
|
},
|
|
"profiles": {
|
|
"minimal": {
|
|
"enabled": ["codeEditor", "documentation"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Usage:
|
|
|
|
1. **Default State** - All features have a default enabled/disabled state
|
|
2. **Environment Overrides** - Override defaults per environment (dev, staging, prod)
|
|
3. **Profiles** - Predefined feature sets (minimal, designer, developer, testing-focused)
|
|
4. **Categories** - Group related features for UI organization
|
|
|
|
---
|
|
|
|
## 🚀 deployment-config.json
|
|
|
|
**Purpose:** Platform-specific deployment configurations and optimizations
|
|
|
|
### Platforms Supported:
|
|
|
|
- ✅ CapRover
|
|
- ✅ Docker Compose
|
|
- ⚪ Heroku (disabled by default)
|
|
- ⚪ Vercel (disabled by default)
|
|
- ⚪ Netlify (disabled by default)
|
|
- ⚪ AWS ECS (disabled by default)
|
|
- ⚪ Kubernetes (disabled by default)
|
|
|
|
### CapRover Configuration:
|
|
|
|
```json
|
|
{
|
|
"platforms": {
|
|
"caprover": {
|
|
"enabled": true,
|
|
"appName": "codeforge",
|
|
"containerHttpPort": 80,
|
|
"healthCheck": {
|
|
"path": "/health",
|
|
"interval": 30
|
|
},
|
|
"buildOptimizations": {
|
|
"simplifiedChunks": true,
|
|
"aggressiveMinification": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Build Profiles:
|
|
|
|
```json
|
|
{
|
|
"buildProfiles": {
|
|
"caprover-optimized": {
|
|
"chunks": {
|
|
"strategy": "simple",
|
|
"groups": {
|
|
"vendor": ["node_modules"],
|
|
"app": ["src"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 pages.json
|
|
|
|
**Purpose:** Define all pages, navigation, shortcuts, and component mappings
|
|
|
|
**Location:** `src/config/pages.json`
|
|
|
|
### Page Structure:
|
|
|
|
```json
|
|
{
|
|
"pages": [
|
|
{
|
|
"id": "dashboard",
|
|
"title": "Dashboard",
|
|
"icon": "ChartBar",
|
|
"component": "ProjectDashboard",
|
|
"enabled": true,
|
|
"shortcut": "ctrl+1",
|
|
"order": 1,
|
|
"props": {
|
|
"state": ["files", "models"],
|
|
"actions": ["onFileChange:handleFileChange"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Page Properties:
|
|
|
|
- `id` - Unique page identifier (used in URLs)
|
|
- `title` - Display name in navigation
|
|
- `icon` - Phosphor icon name
|
|
- `component` - Component name from registry
|
|
- `enabled` - Show/hide page
|
|
- `toggleKey` - Feature toggle key (optional)
|
|
- `shortcut` - Keyboard shortcut (optional)
|
|
- `order` - Navigation order
|
|
- `props` - State and action mappings
|
|
- `resizableConfig` - Split pane configuration (optional)
|
|
|
|
---
|
|
|
|
## 🎨 theme.json
|
|
|
|
**Purpose:** Tailwind theme customization (currently empty, ready for use)
|
|
|
|
**Location:** `theme.json` (root)
|
|
|
|
### Usage:
|
|
|
|
```json
|
|
{
|
|
"extend": {
|
|
"colors": {
|
|
"brand": {
|
|
"50": "#f0f9ff",
|
|
"500": "#3b82f6",
|
|
"900": "#1e3a8a"
|
|
}
|
|
},
|
|
"fontFamily": {
|
|
"custom": ["Custom Font", "sans-serif"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Tailwind config already reads from this file via `tailwind.config.js`
|
|
|
|
---
|
|
|
|
## 🏗️ architecture.json
|
|
|
|
**Purpose:** High-level architecture configuration
|
|
|
|
**Location:** `architecture.json` (root)
|
|
|
|
### Structure:
|
|
|
|
```json
|
|
{
|
|
"pages": {
|
|
"dashboard": {
|
|
"renderer": "json",
|
|
"schema": "./pages/dashboard.json"
|
|
}
|
|
},
|
|
"hooks": {
|
|
"data": ["useDataSource", "useCRUD"],
|
|
"forms": ["useFormField"],
|
|
"ui": ["useDialog"]
|
|
},
|
|
"atomicComponents": {
|
|
"maxLOC": 150,
|
|
"categories": {
|
|
"atoms": [...],
|
|
"molecules": [...],
|
|
"organisms": [...]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Usage Examples
|
|
|
|
### 1. Change App Name and Branding
|
|
|
|
Edit `app.config.json`:
|
|
|
|
```json
|
|
{
|
|
"app": {
|
|
"name": "MyApp",
|
|
"title": "MyApp - Custom Platform",
|
|
"themeColor": "#ff0000"
|
|
}
|
|
}
|
|
```
|
|
|
|
Then update `index.html` to read from config (requires build script)
|
|
|
|
### 2. Enable Experimental Features in Development
|
|
|
|
Edit `feature-toggles.json`:
|
|
|
|
```json
|
|
{
|
|
"environments": {
|
|
"development": {
|
|
"overrides": {
|
|
"modelsJSON": true,
|
|
"componentTreesJSON": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Optimize Build for CapRover
|
|
|
|
Use the `caprover-optimized` build profile from `deployment-config.json`:
|
|
|
|
```bash
|
|
# Set environment variable
|
|
export BUILD_PROFILE=caprover-optimized
|
|
|
|
# Build with profile
|
|
npm run build
|
|
```
|
|
|
|
### 4. Add New Page
|
|
|
|
Edit `src/config/pages.json`:
|
|
|
|
```json
|
|
{
|
|
"pages": [
|
|
{
|
|
"id": "my-page",
|
|
"title": "My Page",
|
|
"icon": "Rocket",
|
|
"component": "MyComponent",
|
|
"enabled": true,
|
|
"order": 100
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Add component to `component-registry.json`:
|
|
|
|
```json
|
|
{
|
|
"components": [
|
|
{
|
|
"name": "MyComponent",
|
|
"path": "@/components/MyComponent",
|
|
"export": "MyComponent",
|
|
"type": "feature",
|
|
"preload": false
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 5. Change Server Port
|
|
|
|
Edit `app.config.json`:
|
|
|
|
```json
|
|
{
|
|
"server": {
|
|
"development": {
|
|
"port": 3000
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Then update `vite.config.ts` to read from config
|
|
|
|
---
|
|
|
|
## 🛠️ Implementation Status
|
|
|
|
| File | Status | Needs Update |
|
|
|------|--------|--------------|
|
|
| app.config.json | ✅ Created | vite.config.ts, index.html |
|
|
| component-registry.json | ✅ Created | component-registry.ts |
|
|
| feature-toggles.json | ✅ Created | FeatureToggleSettings component |
|
|
| deployment-config.json | ✅ Created | Dockerfile, CI/CD scripts |
|
|
| pages.json | ✅ Exists | No changes needed |
|
|
| theme.json | ✅ Supported | Ready for customization |
|
|
| architecture.json | ✅ Exists | No changes needed |
|
|
|
|
---
|
|
|
|
## 🚀 Next Steps
|
|
|
|
### To Use New Configs:
|
|
|
|
1. **Update vite.config.ts** to import `app.config.json`
|
|
2. **Update component-registry.ts** to read from `component-registry.json`
|
|
3. **Update feature toggle hook** to load from `feature-toggles.json`
|
|
4. **Create build script** to generate `index.html` from template + config
|
|
5. **Update Dockerfile** to use `deployment-config.json` settings
|
|
6. **Test all configurations** in development and production
|
|
|
|
### Benefits:
|
|
|
|
- ✅ No rebuilds for config changes (in development)
|
|
- ✅ Environment-specific settings
|
|
- ✅ Platform-optimized builds
|
|
- ✅ Easy customization and branding
|
|
- ✅ Version control friendly
|
|
- ✅ Documentation via JSON schemas
|
|
|
|
---
|
|
|
|
## 📚 Related Documentation
|
|
|
|
- [HARDCODED_ANALYSIS.md](./HARDCODED_ANALYSIS.md) - Detailed analysis of hardcoded values
|
|
- [README.md](./README.md) - Full project documentation
|
|
- [DEPLOYMENT.md](./DEPLOYMENT.md) - Deployment guide
|
|
- [src/config/pages.json](./src/config/pages.json) - Page configuration
|
|
|
|
---
|
|
|
|
**Last Updated:** 2024
|
|
**Version:** 1.0.0
|