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.

my-project/
├── polyglot.json          ← Configuration file
├── package.json
├── services/
└── packages/

Basic Structure

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "name": "simple-api",
  "preset": "none",
  "packageManager": "npm",
  "services": [
    {
      "name": "api",
      "type": "node",
      "port": 3001,
      "path": "services/api"
    }
  ]
}

Full-Stack Application

{
  "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

{
  "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

{
  "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

# 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

# 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:

// ❌ 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:

// ❌ 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:

// ❌ 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:

{
  "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:

{
  "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:

mkdir -p services/api

5. Invalid JSON Syntax

Error: JSON parsing errors.

Solution: Validate JSON syntax:

# 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:

{
  "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:

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:

# 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:

{
  "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:

// turbo.json (when preset: "turbo")
{
  "pipeline": {
    "dev": {
      "dependsOn": ["^build"],
      "persistent": true
    }
  }
}

Best Practices

1. Consistent Naming

Use consistent naming conventions:

{
  "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:

{
  "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:

{
  "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:

## 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:

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:

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:

{
  "services": [
    { "name": "api", "type": "node", "port": 3001, "path": "apps/api" }
  ]
}

New format:

{
  "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 - Available CLI commands
• Service Templates - Service type details
• Getting Started - Basic usage guide
• Docker Integration - Docker setup and usage

Schema Reference

For IDE support, you can reference the JSON schema:

{
  "$schema": "https://raw.githubusercontent.com/kaifcoder/create-polyglot/main/schema/polyglot.schema.json"
}

This enables autocomplete and validation in VS Code and other editors.