Table of Contents

1. Why create-polyglot?
2. Features
3. Quick Start
4. Installation
5. Usage Examples
6. Commands
7. Init Flags / Options
8. Generated Project Structure
9. Presets
10. Development Workflow
11. Docker & Compose Support
12. polyglot.json Configuration
13. Plugins
14. Basic Dev Runner
15. Roadmap
16. Contributing
17. License

Why create-polyglot?

Building a production-style polyglot microservice environment normally requires repetitive boilerplate across languages, Docker files, presets, and configs. create-polyglot automates:

• Consistent folder layout & service naming
• Language starter templates (Node, FastAPI, Go, Spring Boot, Next.js)
• Optional monorepo orchestration (Turborepo or Nx) OR a zero-frills basic runner
• Dockerfile + compose.yaml generation with correct port mappings
• Extensible plugin scaffolding for future lifecycle hooks
• A centralized manifest (polyglot.json) driving subsequent commands (e.g. add service)

Use it to prototype architectures, onboard teams faster, or spin up reproducible demos / PoCs.

Features

• 🚀 Rapid polyglot monorepo scaffolding (Node.js, Python/FastAPI, Go, Java Spring Boot, Next.js)
• 🧩 Optional presets: Turborepo, Nx, or Basic runner
• 🐳 Automatic Dockerfile + Docker Compose generation
• 🛠 Interactive wizard (or fully non-interactive via flags)
• 🔁 Post-init extensibility: add services & plugins anytime
• 📦 Shared package (packages/shared) for cross-service JS utilities
• 🧪 Vitest test setup for the CLI itself
• 🌈 Colorized dev logs & health probing for Node/frontend services
• 🔌 Plugin skeleton generation (create-polyglot add plugin <name>)
• 📄 Single source of truth: polyglot.json
• ✅ Safe guards: port collision checks, reserved name checks, graceful fallbacks
• 📝 Friendly chalk-based CLI output with clear status symbols

Quick Start

Scaffold a workspace named my-org with multiple services:

npx create-polyglot init my-org -s node,python,go,java,frontend --git --yes

Then run everything (Node + frontend locally):

create-polyglot dev

Or via Docker Compose:

create-polyglot dev --docker

Add a new service later:

create-polyglot add service payments --type node --port 4100

Installation

Global (recommended for repeated use):

npm install -g create-polyglot

Local dev / contributing:

npm install
npm link   # or: pnpm link --global / yarn link / bun link

Usage Examples

Interactive wizard (prompts for missing info):

create-polyglot init my-org

Non-interactive with explicit services & git init:

create-polyglot init my-org -s node,python,go --git --yes

Add plugin skeleton:

create-polyglot add plugin postgres

Start dev with Docker:

create-polyglot dev --docker

Commands

Init Options

If you omit flags, the wizard will prompt interactively (similar to create-next-app).

Generated Structure

my-org/
  services/
    node/          # Express + dev script
    python/        # FastAPI + uvicorn
    go/            # Go net/http service
    java/          # Spring Boot (Maven)
    frontend/      # Next.js (template or create-next-app output)
  gateway/
  infra/
  packages/
    shared/
  plugins/         # created when adding plugins
  compose.yaml
  polyglot.json    # persisted configuration
  package.json
  turbo.json / nx.json (if preset chosen)
  scripts/
    dev-basic.cjs

Presets

• Turborepo: Generates turbo.json, sets root dev & build scripts for pipeline caching.
• Nx: Generates nx.json and adjusts scripts accordingly.
• Basic: Minimal setup + scripts/dev-basic.cjs for simple concurrency.

Development Workflow

1. Scaffold with init.
2. (Optional) Add more services or plugins.
3. Run create-polyglot dev (local) or create-polyglot dev --docker.
4. Edit services under services/<name>.
5. Extend infra / databases inside compose.yaml.

Basic Dev Runner

When no preset is chosen, npm run dev uses scripts/dev-basic.cjs:

1. Detects package manager (pnpm > yarn > bun > npm fallback)
2. Scans services/ for Node services
3. Runs those with a dev script
4. Prefixes log lines with service name

Non-Node services start manually or via compose:

cd services/python && uvicorn app.main:app --reload

polyglot dev Command

create-polyglot dev reads polyglot.json, launches Node & frontend services that expose a dev script, assigns each a colorized log prefix, and probes http://localhost:<port>/health until ready (15s timeout). Pass --docker to instead delegate to docker compose up --build for all services.

If a service lacks a dev script it is skipped with no error. Non-Node services (python/go/java) are not auto-started yet unless you choose --docker.

Docker & Compose

For each selected service a Dockerfile is generated. A compose.yaml includes:

• Service definitions with build contexts
• Port mappings (adjust manually if conflicts)
• Shared network app-net

You can extend compose with volumes, env vars, or database services after generation.

Frontend Generation

If --frontend-generator create-next-app is supplied, the tool shells out to npx create-next-app (respecting the chosen package manager for installs). If it fails, a fallback static template is used.

polyglot.json

Example:

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

Used by add service to assert uniqueness and regenerate compose.yaml.

Plugins

create-polyglot add plugin <name> scaffolds plugins/<name>/index.js with a hook skeleton (afterInit). Future releases will execute hooks automatically during lifecycle events.

Shared Package

packages/shared shows cross-service Node utilities. Extend or add per-language shared modules.

Force Overwrite

If the target directory already exists, the CLI aborts unless --force is passed. Use with caution.

Git Initialization

Pass --git to automatically run git init, create an initial commit, and (if desired) you can add remotes afterwards.

Lint & Format

Generates ESLint + Prettier base configs at the root. Extend rules per service if needed.

Roadmap / Ideas

• Plugin hook execution pipeline
• Healthchecks and depends_on in compose.yaml
• Additional generators (Remix, Astro, SvelteKit)
• Automatic test harness & CI workflow template
• Language-specific shared libs (Python package, Go module)
• Hot reload integration aggregator
• Remove service / remove plugin commands

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines. Please run tests before submitting a PR:

npm test

License

MIT

Documentation Site (VitePress)

Local docs development:

npm run docs:dev

Build static site:

npm run docs:build

Preview production build:

npm run docs:preview

Docs source lives in docs/ with sidebar-driven structure defined in docs/.vitepress/config.mjs.

Deployment

Docs are auto-deployed to GitHub Pages on pushes to main that touch docs/ via .github/workflows/docs.yml. The base path is set using VITEPRESS_BASE=/create-polyglot/.

Installation (local dev)

npm install
npm link # or: pnpm link --global / yarn link / bun link

Then run (non-interactive example):

create-polyglot init my-org -s node,python,go,java,frontend --git --yes

Interactive (wizard prompts for any missing info):

create-polyglot init my-org

Add a service later:

create-polyglot add service payments --type node --port 4100

Add a plugin scaffold:

create-polyglot add plugin postgres

Run all services in dev mode (Node & frontend locally; others manual unless using docker):

create-polyglot dev

Run everything via Docker Compose:

create-polyglot dev --docker

Commands

Init Options

If you omit flags, the wizard will prompt interactively (similar to create-next-app).

Generated Structure

my-org/
  services/
    node/          # Express + dev script
    python/        # FastAPI + uvicorn
    go/            # Go net/http service
    java/          # Spring Boot (Maven)
    frontend/      # Next.js (template or create-next-app output)
  gateway/
  infra/
  packages/
    shared/
  plugins/         # created when adding plugins
  compose.yaml
  polyglot.json    # persisted configuration
  package.json
  turbo.json / nx.json (if preset chosen)
  scripts/
    dev-basic.cjs

Presets

• Turborepo: Generates turbo.json, sets root dev & build scripts to leverage Turborepo pipelines.
• Nx: Generates nx.json and adjusts scripts accordingly.
• Basic: Provides a minimal setup plus scripts/dev-basic.cjs for simple concurrency.

Basic Dev Runner

When no preset is chosen, npm run dev uses scripts/dev-basic.cjs:

1. Detects package manager (pnpm > yarn > bun > npm fallback)
2. Scans services/ for Node services
3. Runs those with a dev script
4. Prefixes log lines with service name

Non-Node services start manually or via compose:

cd services/python && uvicorn app.main:app --reload

polyglot dev Command

create-polyglot dev reads polyglot.json, launches Node & frontend services that expose a dev script, assigns each a colorized log prefix, and probes http://localhost:<port>/health until ready (15s timeout). Pass --docker to instead delegate to docker compose up --build for all services.

If a service lacks a dev script it is skipped with no error. Non-Node services (python/go/java) are not auto-started yet unless you choose --docker.

Docker & Compose

For each selected service a Dockerfile is generated. A compose.yaml includes:

• Service definitions with build contexts
• Port mappings (adjust manually if conflicts)
• Shared network app-net You can extend compose with volumes, env vars, or database services after generation.

Frontend Generation

If --frontend-generator create-next-app is supplied, the tool shells out to npx create-next-app (respecting the chosen package manager for installs). If it fails, a fallback static template is used.

polyglot.json

Example:

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

Used by add service to assert uniqueness and regenerate compose.yaml.

Plugins

create-polyglot add plugin <name> scaffolds plugins/<name>/index.js with a hook skeleton (afterInit). Future releases will execute hooks automatically during lifecycle events.

Shared Package

packages/shared shows cross-service Node utilities. Extend or add per-language shared modules.

Force Overwrite

If the target directory already exists, the CLI aborts unless --force is passed. Use with caution.

Git Initialization

Pass --git to automatically run git init, create an initial commit, and (if desired) you can add remotes afterwards.

Lint & Format

Generates ESLint + Prettier base configs at the root. Extend rules per service if needed.

Roadmap / Ideas

• Plugin hook execution pipeline
• Healthchecks and depends_on in compose.yaml
• Additional generators (Remix, Astro, SvelteKit)
• Automatic test harness & CI workflow template
• Language-specific shared libs (Python package, Go module)
• Hot reload integration aggregator
• Remove service / remove plugin commands

License

MIT

Documentation Site (VitePress)

Local docs development:

npm run docs:dev

Build static site:

npm run docs:build

Preview production build:

npm run docs:preview

Docs source lives in docs/ with sidebar-driven structure defined in docs/.vitepress/config.mjs.

Deployment

Docs are auto-deployed to GitHub Pages on pushes to main that touch docs/ via .github/workflows/docs.yml. The base path is set using VITEPRESS_BASE=/create-polyglot/.