create-polyglot

Scaffold a modern polyglot microservices monorepo in seconds.
Generate Node.js, Python (FastAPI), Go, Java (Spring Boot), and Next.js frontend services with optional Turborepo or Nx presets, Docker Compose, shared packages, plugin hooks, and a persisted configuration file.

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

Command	Description
`create-polyglot init <name>`	Scaffold a new workspace (root invocation without `init` is deprecated).
`create-polyglot add service <name>`	Add a service after init (`--type`, `--port`, `--yes`).
`create-polyglot add plugin <name>`	Create plugin skeleton under `plugins/<name>`.
`create-polyglot dev [--docker]`	Run Node & frontend services locally or all via compose.

Init Options

Flag	Description
`-s, --services <list>`	Comma separated services: `node,python,go,java,frontend`
`--preset <name>`	`turborepo`, `nx`, or `basic` (default auto -> asks)
`--git`	Initialize git repo & initial commit
`--no-install`	Skip dependency installation step
`--package-manager <pm>`	One of `npm
`--frontend-generator`	Use `create-next-app` (falls back to template on failure)
`--force`	Overwrite existing target directory if it exists
`--yes`	Accept defaults & suppress interactive prompts

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

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

Basic Dev Runner

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

Detects package manager (pnpm > yarn > bun > npm fallback)
Scans services/ for Node services
Runs those with a dev script
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

Command	Description
`create-polyglot init <name>`	Scaffold a new workspace (root invocation without `init` is deprecated).
`create-polyglot add service <name>`	Add a service after init (`--type`, `--port`, `--yes`).
`create-polyglot add plugin <name>`	Create plugin skeleton under `plugins/<name>`.
`create-polyglot dev [--docker]`	Run Node & frontend services locally or all via compose.

Init Options

Flag	Description
`-s, --services <list>`	Comma separated services: `node,python,go,java,frontend`
`--preset <name>`	`turborepo`, `nx`, or `basic` (default auto -> asks)
`--git`	Initialize git repo & initial commit
`--no-install`	Skip dependency installation step
`--package-manager <pm>`	One of `npm
`--frontend-generator`	Use `create-next-app` (falls back to template on failure)
`--force`	Overwrite existing target directory if it exists

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:

Detects package manager (pnpm > yarn > bun > npm fallback)
Scans services/ for Node services
Runs those with a dev script
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/.

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.copilot		.copilot
.github		.github
.vscode		.vscode
bin		bin
docs		docs
scripts		scripts
templates		templates
test-workspace		test-workspace
tests		tests
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yaml		docker-compose.yaml
package-lock.json		package-lock.json
package.json		package.json

License

kaifcoder/create-polyglot

Folders and files

Latest commit

History

Repository files navigation

create-polyglot

Table of Contents

Why create-polyglot?

Features

Quick Start

Installation

Usage Examples

Commands

Init Options

Generated Structure

Presets

Development Workflow

Basic Dev Runner

polyglot dev Command

Docker & Compose

Frontend Generation

polyglot.json

Plugins

Shared Package

Force Overwrite

Git Initialization

Lint & Format

Roadmap / Ideas

Contributing

License

Documentation Site (VitePress)

Deployment

Installation (local dev)

Commands

Init Options

Generated Structure

Presets

Basic Dev Runner

polyglot dev Command

Docker & Compose

Frontend Generation

polyglot.json

Plugins

Shared Package

Force Overwrite

Git Initialization

Lint & Format

Roadmap / Ideas

License

Documentation Site (VitePress)

Deployment

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors 7

Uh oh!

Languages

Packages