From e81fad96b1baacf44e24e21a8f626ed5ad6c9bef Mon Sep 17 00:00:00 2001 From: meenu155 Date: Wed, 12 Nov 2025 21:48:33 +0530 Subject: [PATCH 1/2] feat(docs): add comprehensive polyglot.json configuration reference --- docs/configuration/polyglot-json.md | 779 ++++++++++++++++++++++++++++ 1 file changed, 779 insertions(+) create mode 100644 docs/configuration/polyglot-json.md diff --git a/docs/configuration/polyglot-json.md b/docs/configuration/polyglot-json.md new file mode 100644 index 0000000..095e62d --- /dev/null +++ b/docs/configuration/polyglot-json.md @@ -0,0 +1,779 @@ +# polyglot.json Configuration Reference + +The `polyglot.json` file is the heart of your create-polyglot workspace. It defines your project structure, services, and configuration options. This file is automatically generated when you run `create-polyglot init` and is used by all CLI commands to understand your workspace layout. + +## File Location + +The `polyglot.json` file must be located in the root directory of your workspace. All create-polyglot commands expect to find this file in the current working directory. + +```text +my-project/ +├── polyglot.json ← Configuration file +├── package.json +├── services/ +└── packages/ +``` + +## Basic Structure + +```json +{ + "name": "my-project", + "preset": "none", + "packageManager": "npm", + "services": [ + { + "name": "api", + "type": "node", + "port": 3001, + "path": "services/api" + } + ] +} +``` + +## Configuration Fields + +### Root Level Fields + +#### `name` (string, required) + +The name of your project workspace. + +**Example:** + +```json +{ + "name": "my-ecommerce-app" +} +``` + +**Impact:** + +- Used in CLI output and logging +- Displayed in admin dashboard +- Used as default name for Docker containers + +#### `preset` (string, required) + +The monorepo preset used for your workspace. + +**Valid values:** + +- `"none"` - No preset, basic setup +- `"turbo"` - Turborepo configuration +- `"nx"` - Nx workspace configuration + +**Example:** + +```json +{ + "preset": "turbo" +} +``` + +**Impact:** + +- Determines which configuration files are generated (`turbo.json`, `nx.json`) +- Affects the dev script behavior in root `package.json` +- Changes how services are orchestrated during development + +#### `packageManager` (string, required) + +The package manager used throughout the workspace. + +**Valid values:** + +- `"npm"` +- `"yarn"` +- `"pnpm"` +- `"bun"` + +**Example:** + +```json +{ + "packageManager": "pnpm" +} +``` + +**Impact:** + +- Used in generated scripts and commands +- Affects lock file handling +- Determines installation commands in CI/CD workflows +- Used by service manager for dependency installation + +#### `services` (array, required) + +Array of service configurations. Each service represents a deployable unit in your workspace. + +**Example:** + +```json +{ + "services": [ + { + "name": "api", + "type": "node", + "port": 3001, + "path": "services/api" + }, + { + "name": "frontend", + "type": "frontend", + "port": 3000, + "path": "services/frontend" + } + ] +} +``` + +### Service Configuration + +Each service in the `services` array must include these fields: + +#### Service `name` (string, required) + +Unique identifier for the service within the workspace. + +**Rules:** + +- Must be unique across all services +- Cannot contain spaces or special characters +- Should use kebab-case or camelCase +- Cannot be reserved names: `node_modules`, `dist`, `build`, `public` + +**Examples:** + +```json +{ + "name": "user-api" // ✅ Good +} +{ + "name": "userAPI" // ✅ Good +} +{ + "name": "user api" // ❌ Bad - contains space +} +{ + "name": "node_modules" // ❌ Bad - reserved name +} +``` + +#### `type` (string, required) + +The technology stack/framework used by the service. + +**Valid values:** + +- `"node"` - Node.js service (Express, Fastify, etc.) +- `"frontend"` - Frontend application (React, Vue, Next.js, etc.) +- `"python"` - Python service (FastAPI, Flask, Django, etc.) +- `"go"` - Go service +- `"java"` - Java service (Spring Boot, etc.) + +**Example:** + +```json +{ + "type": "node" +} +``` + +**Impact:** + +- Determines the service template used during generation +- Affects Docker configuration and build process +- Influences service manager start commands +- Used for health checks and status monitoring + +#### `port` (number, required) + +The port number the service listens on. + +**Rules:** + +- Must be a valid port number (1-65535) +- Must be unique across all services in the workspace +- Common ranges: 3000-3999 for development + +**Example:** + +```json +{ + "port": 3001 +} +``` + +**Impact:** + +- Used in service URLs and health checks +- Configured in Docker Compose networking +- Used by admin dashboard for service links +- Required for service-to-service communication + +#### `path` (string, required) + +The relative path from workspace root to the service directory. + +**Rules:** + +- Must be a valid relative path +- Typically follows pattern: `services/{service-name}` +- Directory must exist and contain service files + +**Example:** + +```json +{ + "path": "services/api" +} +``` + +**Impact:** + +- Used by CLI commands to locate service files +- Affects service manager working directory +- Used in Docker build context +- Required for log file location + +## Complete Examples + +### Simple Node.js API + +```json +{ + "name": "simple-api", + "preset": "none", + "packageManager": "npm", + "services": [ + { + "name": "api", + "type": "node", + "port": 3001, + "path": "services/api" + } + ] +} +``` + +### Full-Stack Application + +```json +{ + "name": "my-fullstack-app", + "preset": "turbo", + "packageManager": "pnpm", + "services": [ + { + "name": "frontend", + "type": "frontend", + "port": 3000, + "path": "services/frontend" + }, + { + "name": "api", + "type": "node", + "port": 3001, + "path": "services/api" + }, + { + "name": "auth-service", + "type": "node", + "port": 3002, + "path": "services/auth-service" + } + ] +} +``` + +### Microservices Architecture + +```json +{ + "name": "microservices-platform", + "preset": "nx", + "packageManager": "yarn", + "services": [ + { + "name": "web-app", + "type": "frontend", + "port": 3000, + "path": "services/web-app" + }, + { + "name": "user-api", + "type": "node", + "port": 3001, + "path": "services/user-api" + }, + { + "name": "product-api", + "type": "python", + "port": 3002, + "path": "services/product-api" + }, + { + "name": "order-service", + "type": "java", + "port": 3003, + "path": "services/order-service" + }, + { + "name": "notification-service", + "type": "go", + "port": 3004, + "path": "services/notification-service" + } + ] +} +``` + +### Polyglot Setup + +```json +{ + "name": "polyglot-ecommerce", + "preset": "turbo", + "packageManager": "pnpm", + "services": [ + { + "name": "storefront", + "type": "frontend", + "port": 3000, + "path": "services/storefront" + }, + { + "name": "api-gateway", + "type": "node", + "port": 3001, + "path": "services/api-gateway" + }, + { + "name": "user-service", + "type": "java", + "port": 3002, + "path": "services/user-service" + }, + { + "name": "product-catalog", + "type": "python", + "port": 3003, + "path": "services/product-catalog" + }, + { + "name": "inventory-service", + "type": "go", + "port": 3004, + "path": "services/inventory-service" + }, + { + "name": "payment-processor", + "type": "node", + "port": 3005, + "path": "services/payment-processor" + } + ] +} +``` + +## CLI Commands That Use polyglot.json + +### Service Management + +```bash +# List all services +create-polyglot services + +# Add a new service +create-polyglot add service my-service --type node --port 3006 + +# Start development servers +create-polyglot dev + +# Run with Docker +create-polyglot dev --docker +``` + +### Monitoring and Admin + +```bash +# Launch admin dashboard +create-polyglot admin + +# View service logs +create-polyglot logs + +# Hot reload services +create-polyglot hot +``` + +### Service Status + +All commands read the `services` array to understand which services exist and their configuration. + +## Validation Rules + +### Port Conflicts + +Each service must have a unique port number: + +```json +// ❌ Invalid - port conflict +{ + "services": [ + { "name": "api", "type": "node", "port": 3000, "path": "services/api" }, + { "name": "web", "type": "frontend", "port": 3000, "path": "services/web" } + ] +} + +// ✅ Valid - unique ports +{ + "services": [ + { "name": "api", "type": "node", "port": 3001, "path": "services/api" }, + { "name": "web", "type": "frontend", "port": 3000, "path": "services/web" } + ] +} +``` + +### Service Name Conflicts + +Each service must have a unique name: + +```json +// ❌ Invalid - name conflict +{ + "services": [ + { "name": "api", "type": "node", "port": 3001, "path": "services/api" }, + { "name": "api", "type": "python", "port": 3002, "path": "services/api-v2" } + ] +} + +// ✅ Valid - unique names +{ + "services": [ + { "name": "api", "type": "node", "port": 3001, "path": "services/api" }, + { "name": "api-v2", "type": "python", "port": 3002, "path": "services/api-v2" } + ] +} +``` + +### Path Validation + +Service paths must exist and be accessible: + +```json +// ❌ Invalid - path doesn't exist +{ + "services": [ + { "name": "api", "type": "node", "port": 3001, "path": "nonexistent/path" } + ] +} + +// ✅ Valid - path exists +{ + "services": [ + { "name": "api", "type": "node", "port": 3001, "path": "services/api" } + ] +} +``` + +## Common Mistakes and Solutions + +### 1. Missing polyglot.json + +**Error:** `polyglot.json not found. Run inside a generated workspace.` + +**Solution:** Ensure you're running commands from the workspace root where `polyglot.json` exists. + +### 2. Port Already in Use + +**Error:** Service fails to start due to port conflicts. + +**Solution:** Update port numbers in `polyglot.json` to use unique values: + +```json +{ + "services": [ + { "name": "api", "port": 3001 }, + { "name": "web", "port": 3000 } + ] +} +``` + +### 3. Invalid Service Type + +**Error:** Unknown service type during scaffolding. + +**Solution:** Use only supported service types: + +```json +{ + "type": "node" // ✅ Supported +} +{ + "type": "react" // ❌ Use "frontend" instead +} +``` + +### 4. Service Directory Not Found + +**Error:** Service directory doesn't exist. + +**Solution:** Ensure service directories exist and match the `path` field: + +```bash +mkdir -p services/api +``` + +### 5. Invalid JSON Syntax + +**Error:** JSON parsing errors. + +**Solution:** Validate JSON syntax: + +```bash +# Check JSON validity +npx jsonlint polyglot.json + +# Use proper JSON format +{ + "name": "my-project", // ✅ Proper string + "port": 3001, // ✅ Proper number + "enabled": true // ✅ Proper boolean +} +``` + +## Modifying polyglot.json + +### Adding Services Manually + +You can manually edit `polyglot.json` to add services: + +```json +{ + "services": [ + { + "name": "new-service", + "type": "python", + "port": 3005, + "path": "services/new-service" + } + ] +} +``` + +After manual changes: + +1. Create the service directory +2. Add appropriate service files +3. Run `create-polyglot services` to verify + +### Using the CLI + +Recommended approach using the CLI: + +```bash +create-polyglot add service new-service --type python --port 3005 +``` + +This automatically: + +- Updates `polyglot.json` +- Creates service directory +- Scaffolds service files +- Validates configuration + +## Integration with Other Tools + +### Docker Compose + +The `services` array is used to generate `compose.yaml`: + +```yaml +# Generated from polyglot.json +services: + api: + build: ./services/api + ports: + - "3001:3001" + web: + build: ./services/web + ports: + - "3000:3000" +``` + +### Package Scripts + +Root `package.json` scripts reference services: + +```json +{ + "scripts": { + "dev": "concurrently npm:dev:*", + "dev:api": "cd services/api && npm run dev", + "dev:web": "cd services/web && npm run dev" + } +} +``` + +### Turborepo/Nx Configuration + +Preset field generates workspace configuration: + +```json +// turbo.json (when preset: "turbo") +{ + "pipeline": { + "dev": { + "dependsOn": ["^build"], + "persistent": true + } + } +} +``` + +## Best Practices + +### 1. Consistent Naming + +Use consistent naming conventions: + +```json +{ + "services": [ + { "name": "user-api", "path": "services/user-api" }, + { "name": "product-api", "path": "services/product-api" }, + { "name": "order-api", "path": "services/order-api" } + ] +} +``` + +### 2. Logical Port Assignment + +Assign ports logically: + +```json +{ + "services": [ + { "name": "frontend", "port": 3000 }, // Frontend on 3000 + { "name": "api-gateway", "port": 3001 }, // Gateway on 3001 + { "name": "user-service", "port": 3002 }, // Services on 3002+ + { "name": "auth-service", "port": 3003 } + ] +} +``` + +### 3. Group Related Services + +Organize services logically: + +```json +{ + "services": [ + // Frontend services + { "name": "web-app", "type": "frontend", "port": 3000 }, + { "name": "admin-panel", "type": "frontend", "port": 3010 }, + + // API services + { "name": "api-gateway", "type": "node", "port": 3001 }, + { "name": "user-api", "type": "node", "port": 3002 }, + + // Background services + { "name": "worker", "type": "python", "port": 3020 } + ] +} +``` + +### 4. Document Your Configuration + +Add comments in your README about service purposes: + +```markdown +## Services + +- `web-app` (port 3000) - Main customer-facing application +- `admin-panel` (port 3010) - Internal admin dashboard +- `api-gateway` (port 3001) - API gateway and routing +- `user-api` (port 3002) - User management service +- `worker` (port 3020) - Background job processor +``` + +## Troubleshooting + +### Configuration Validation + +Run this command to validate your configuration: + +```bash +create-polyglot services --json | jq . +``` + +### Common Issues + +1. **Service won't start**: Check port conflicts and service directory existence +2. **Admin dashboard shows errors**: Verify all services are properly configured +3. **Docker build fails**: Ensure service paths are correct +4. **CLI commands fail**: Confirm you're in the workspace root directory + +### Debug Mode + +Use verbose output to debug configuration issues: + +```bash +DEBUG=create-polyglot:* create-polyglot services +``` + +## Migration Guide + +### From Legacy Structure + +If you have an older create-polyglot project, you may need to update your `polyglot.json`: + +**Old format:** + +```json +{ + "services": [ + { "name": "api", "type": "node", "port": 3001, "path": "apps/api" } + ] +} +``` + +**New format:** + +```json +{ + "services": [ + { "name": "api", "type": "node", "port": 3001, "path": "services/api" } + ] +} +``` + +### Updating Service Paths + +If you need to update service paths: + +1. Move service directories: `mv apps/api services/api` +2. Update `polyglot.json` paths +3. Update any hardcoded references in scripts + +## Related Documentation + +- [CLI Commands](../cli/index.md) - Available CLI commands +- [Service Templates](../templates/index.md) - Service type details +- [Getting Started](../guide/getting-started.md) - Basic usage guide +- [Docker Integration](../guide/docker.md) - Docker setup and usage + +## Schema Reference + +For IDE support, you can reference the JSON schema: + +```json +{ + "$schema": "https://raw.githubusercontent.com/kaifcoder/create-polyglot/main/schema/polyglot.schema.json" +} +``` + +This enables autocomplete and validation in VS Code and other editors. \ No newline at end of file From 266c80bba9632809280b3158a8a49d9eb14daadd Mon Sep 17 00:00:00 2001 From: meenu155 Date: Wed, 12 Nov 2025 23:12:14 +0530 Subject: [PATCH 2/2] docs: add missing navigation links to VitePress config - Add Configuration nav item for polyglot.json reference - Add Admin Dashboard link to CLI sidebar - Add Plugin System and Service Controls to guide sidebar - Create new configuration sidebar section - Ensure all available documentation files are accessible --- docs/.vitepress/config.mjs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 3dc034d..a4059df 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -17,6 +17,7 @@ export default defineConfig({ { text: 'Guide', link: '/guide/' }, { text: 'CLI', link: '/cli/' }, { text: 'Templates', link: '/templates/' }, + { text: 'Configuration', link: '/configuration/polyglot-json' }, { text: 'Features', link: '/logs-feature' } ], sidebar: { @@ -26,12 +27,18 @@ export default defineConfig({ { text: 'Presets', link: '/guide/presets' }, { text: 'Docker & Compose', link: '/guide/docker' }, { text: 'Extending (New Service)', link: '/guide/extending-service' }, - { text: 'Service Logs', link: '/logs-feature' } + { text: 'Service Logs', link: '/logs-feature' }, + { text: 'Plugin System', link: '/plugin-system' }, + { text: 'Service Controls', link: '/service-controls-feature' } ], '/cli/': [ { text: 'Usage', link: '/cli/' }, + { text: 'Admin Dashboard', link: '/cli/admin' }, { text: 'Flags', link: '/cli/flags' } ], + '/configuration/': [ + { text: 'polyglot.json', link: '/configuration/polyglot-json' } + ], '/templates/': [ { text: 'Overview', link: '/templates/' }, { text: 'Node', link: '/templates/node' },