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:

Create the service directory
Add appropriate service files
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

Service won't start: Check port conflicts and service directory existence
Admin dashboard shows errors: Verify all services are properly configured
Docker build fails: Ensure service paths are correct
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:

Move service directories: mv apps/api services/api
Update polyglot.json paths
Update any hardcoded references in scripts

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.

Uh oh!

FilesExpand file tree

polyglot-json.md

Latest commit

History

polyglot-json.md

File metadata and controls

polyglot.json Configuration Reference

File Location

Basic Structure

Configuration Fields

Root Level Fields

name (string, required)

preset (string, required)

packageManager (string, required)

services (array, required)

Service Configuration

Service name (string, required)

type (string, required)

port (number, required)

path (string, required)

Complete Examples

Simple Node.js API

Full-Stack Application

Microservices Architecture

Polyglot Setup

CLI Commands That Use polyglot.json

Service Management

Monitoring and Admin

Service Status

Validation Rules

Port Conflicts

Service Name Conflicts

Path Validation

Common Mistakes and Solutions

1. Missing polyglot.json

2. Port Already in Use

3. Invalid Service Type

4. Service Directory Not Found

5. Invalid JSON Syntax

Modifying polyglot.json

Adding Services Manually

Using the CLI

Integration with Other Tools

Docker Compose

Package Scripts

Turborepo/Nx Configuration

Best Practices

1. Consistent Naming

2. Logical Port Assignment

3. Group Related Services

4. Document Your Configuration

Troubleshooting

Configuration Validation

Common Issues

Debug Mode

Migration Guide

From Legacy Structure

Updating Service Paths

Related Documentation

Schema Reference

`name` (string, required)

`preset` (string, required)

`packageManager` (string, required)

`services` (array, required)

Service `name` (string, required)

`type` (string, required)

`port` (number, required)

`path` (string, required)