mirror of
https://github.com/johndoe6345789/low-code-react-app-b.git
synced 2026-04-24 21:54:56 +00:00
Generated by Spark: Identify hard coded stuff that can be moved to json - worth reading project incl README.md first.
This commit is contained in:
GitHub
485
JSON_CONFIG_GUIDE.md
Normal file
485
JSON_CONFIG_GUIDE.md
Normal file
@@ -0,0 +1,485 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user