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?
- Features
- Quick Start
- Installation
- Usage Examples
- Commands
- Init Flags / Options
- Generated Project Structure
- Presets
- Development Workflow
- Docker & Compose Support
- polyglot.json Configuration
- Plugins
- Basic Dev Runner
- Roadmap
- Contributing
- License
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.yamlgeneration 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.
- 🚀 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
- 🔥 Unified hot reload aggregator (
create-polyglot hot) for Node, Next.js, Python (uvicorn), Go, and Java (Spring Boot) - 🔌 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
- 📡 Admin dashboard with real-time log streaming (chokidar file watching, no manual refresh needed)
Scaffold a workspace named my-org with multiple services:
| create-polyglot hot [--services <subset>] [--dry-run] | Unified hot reload (restart / HMR) across services. |
npx create-polyglot init my-org -s node,python,go,java,frontend --git --yesThen run everything (Node + frontend locally):
create-polyglot devUnified hot reload (auto restart / HMR):
create-polyglot hotDry run (see what would execute without starting processes):
create-polyglot hot --dry-runLimit to a subset (by names or types):
create-polyglot hot --services node,pythonOr via Docker Compose:
create-polyglot dev --dockerAdd a new service later:
create-polyglot add service payments --type node --port 4100If you omit --services, the CLI now asks:
- "How many services do you want to create?" (enter a number)
- For each service: choose a type (Node, Python, Go, Java, Frontend)
- Optionally enter a custom name (blank keeps the default type name)
- Optionally override the suggested port (blank keeps default)
Example (interactive):
create-polyglot init my-org
# > How many services? 3
# > Service #1 type: Node.js (Express)
# > Name for node service: api
# > Port for api (node) (default 3001): 4001
# > Service #2 type: Python (FastAPI)
# > Name for python service: (enter) # keeps 'python'
# > Port for python (python) (default 3004): (enter)
# > Service #3 type: Frontend (Next.js)
# ...Non-interactive (--yes) still scaffolds exactly one node service by default for speed.
Global (recommended for repeated use):
npm install -g create-polyglotLocal dev / contributing:
npm install
npm link # or: pnpm link --global / yarn link / bun linkInteractive wizard (prompts for missing info):
create-polyglot init my-orgNon-interactive with explicit services & git init:
create-polyglot init my-org -s node,python,go --git --yesAdd plugin skeleton:
create-polyglot add plugin postgresStart dev with Docker:
create-polyglot dev --docker| 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. |
| 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 |
--with-actions |
Generate a starter GitHub Actions CI workflow (.github/workflows/ci.yml) |
--yes |
Accept defaults & suppress interactive prompts |
If you omit flags, the wizard will prompt interactively (similar to create-next-app).
Pass --with-actions (or answer "yes" to the prompt) and the scaffold adds a minimal workflow at .github/workflows/ci.yml that:
- Triggers on pushes & pull requests targeting
main/master - Sets up Node.js (20.x) with dependency cache
- Installs dependencies (respects your chosen package manager)
- Runs the test suite (
npm test/yarn test/pnpm test/bun test)
You can extend it with build, lint, docker publish, or matrix strategies. If you skip it initially you can always add later manually.
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/
npx create-polyglot dev
- Turborepo: Generates
turbo.json, sets rootdev&buildscripts for pipeline caching. - Nx: Generates
nx.jsonand adjusts scripts accordingly. - Basic: Minimal setup +
npx create-polyglot devfor simple concurrency.
- Scaffold with
init. - (Optional) Add more services or plugins.
- Run
create-polyglot dev(local) orcreate-polyglot dev --docker. - Edit services under
services/<name>. - Extend infra / databases inside
compose.yaml.
When no preset is chosen, npm run dev uses npx create-polyglot dev:
- Detects package manager (pnpm > yarn > bun > npm fallback)
- Scans
services/for Node services - Runs those with a
devscript - Prefixes log lines with service name
Non-Node services start manually or via compose:
cd services/python && uvicorn app.main:app --reloadcreate-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.
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.
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.
Example:
Used by add service to assert uniqueness and regenerate compose.yaml.
create-polyglot add plugin <name> scaffolds plugins/<name>/index.js with a hook skeleton (afterInit). Future releases will execute hooks automatically during lifecycle events.
packages/shared shows cross-service Node utilities. Extend or add per-language shared modules.
If the target directory already exists, the CLI aborts unless --force is passed. Use with caution.
Pass --git to automatically run git init, create an initial commit, and (if desired) you can add remotes afterwards.
Generates ESLint + Prettier base configs at the root. Extend rules per service if needed.
- 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
Contributions welcome! See CONTRIBUTING.md for guidelines. Please run tests before submitting a PR:
npm testMIT
Local docs development:
npm run docs:devBuild static site:
npm run docs:buildPreview production build:
npm run docs:previewDocs source lives in docs/ with sidebar-driven structure defined in docs/.vitepress/config.mjs.
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/.
npm install
npm link # or: pnpm link --global / yarn link / bun linkThen run (non-interactive example):
create-polyglot init my-org -s node,python,go,java,frontend --git --yesInteractive (wizard prompts for any missing info):
create-polyglot init my-orgAdd a service later:
create-polyglot add service payments --type node --port 4100Add a plugin scaffold:
create-polyglot add plugin postgresRun all services in dev mode (Node & frontend locally; others manual unless using docker):
create-polyglot devRun everything via Docker Compose:
create-polyglot dev --docker| 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. |
| 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).
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/
npx create-polyglot dev
- Turborepo: Generates
turbo.json, sets rootdev&buildscripts to leverage Turborepo pipelines. - Nx: Generates
nx.jsonand adjusts scripts accordingly. - Basic: Provides a minimal setup plus
npx create-polyglot devfor simple concurrency.
When no preset is chosen, npm run dev uses npx create-polyglot dev:
- Detects package manager (pnpm > yarn > bun > npm fallback)
- Scans
services/for Node services - Runs those with a
devscript - Prefixes log lines with service name
Non-Node services start manually or via compose:
cd services/python && uvicorn app.main:app --reload
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.
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-netYou can extend compose with volumes, env vars, or database services after 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.
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.
create-polyglot add plugin <name> scaffolds plugins/<name>/index.js with a hook skeleton (afterInit). Future releases will execute hooks automatically during lifecycle events.
packages/shared shows cross-service Node utilities. Extend or add per-language shared modules.
If the target directory already exists, the CLI aborts unless --force is passed. Use with caution.
Pass --git to automatically run git init, create an initial commit, and (if desired) you can add remotes afterwards.
Generates ESLint + Prettier base configs at the root. Extend rules per service if needed.
- 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
MIT
Local docs development:
npm run docs:devBuild static site:
npm run docs:buildPreview production build:
npm run docs:previewDocs source lives in docs/ with sidebar-driven structure defined in docs/.vitepress/config.mjs.
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": "my-org", "preset": "none", "packageManager": "npm", "services": [ { "name": "node", "type": "node", "port": 3001, "path": "services/node" } ] }