{"id":32368946,"url":"https://github.com/kaifcoder/create-polyglot","last_synced_at":"2025-10-24T19:36:46.204Z","repository":{"id":318144392,"uuid":"1070139317","full_name":"kaifcoder/create-polyglot","owner":"kaifcoder","description":"Scaffold polyglot microservice monorepos with built-in templates for Node, Python, Go, and more.","archived":false,"fork":false,"pushed_at":"2025-10-24T08:43:17.000Z","size":182,"stargazers_count":4,"open_issues_count":12,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-24T10:09:02.052Z","etag":null,"topics":["hacktoberfest","microservice","npm","nx","polyglot","turborepo"],"latest_commit_sha":null,"homepage":"https://kaifcoder.github.io/create-polyglot/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaifcoder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-05T10:53:10.000Z","updated_at":"2025-10-24T08:43:21.000Z","dependencies_parsed_at":"2025-10-09T00:34:42.258Z","dependency_job_id":null,"html_url":"https://github.com/kaifcoder/create-polyglot","commit_stats":null,"previous_names":["kaifcoder/create-polyglot"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/kaifcoder/create-polyglot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fcreate-polyglot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fcreate-polyglot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fcreate-polyglot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fcreate-polyglot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaifcoder","download_url":"https://codeload.github.com/kaifcoder/create-polyglot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fcreate-polyglot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280857053,"owners_count":26403190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-24T02:00:06.418Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","microservice","npm","nx","polyglot","turborepo"],"created_at":"2025-10-24T19:36:38.078Z","updated_at":"2025-10-24T19:36:46.187Z","avatar_url":"https://github.com/kaifcoder.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# create-polyglot\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/kaifcoder/create-polyglot/npm-publish.yml?branch=main)](https://github.com/kaifcoder/create-polyglot/actions)\n[![License](https://img.shields.io/github/license/kaifcoder/create-polyglot.svg)](https://github.com/kaifcoder/create-polyglot/blob/main/LICENSE)\n[![Latest Release](https://img.shields.io/github/v/release/kaifcoder/create-polyglot)](https://github.com/kaifcoder/create-polyglot/releases)\n[![Open Issues](https://img.shields.io/github/issues/kaifcoder/create-polyglot)](https://github.com/kaifcoder/create-polyglot/issues)\n[![Open PRs](https://img.shields.io/github/issues-pr/kaifcoder/create-polyglot)](https://github.com/kaifcoder/create-polyglot/pulls)\n[![Languages](https://img.shields.io/github/languages/top/kaifcoder/create-polyglot)](https://github.com/kaifcoder/create-polyglot)\n[![Coverage](https://img.shields.io/codecov/c/github/kaifcoder/create-polyglot)](https://codecov.io/gh/kaifcoder/create-polyglot)\n[![Contributors](https://img.shields.io/github/contributors/kaifcoder/create-polyglot)](https://github.com/kaifcoder/create-polyglot/graphs/contributors)\n[![npm version](https://img.shields.io/npm/v/create-polyglot.svg)](https://www.npmjs.com/package/create-polyglot)\n[![npm downloads](https://img.shields.io/npm/dw/create-polyglot.svg)](https://www.npmjs.com/package/create-polyglot)\n\n\u003cstrong\u003eScaffold a modern polyglot microservices monorepo in seconds.\u003c/strong\u003e\u003cbr/\u003e\nGenerate 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.\n\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n1. [Why create-polyglot?](#why-create-polyglot)\n2. [Features](#features)\n3. [Quick Start](#quick-start)\n4. [Installation](#installation)\n5. [Usage Examples](#usage-examples)\n6. [Commands](#commands)\n7. [Init Flags / Options](#init-options)\n8. [Generated Project Structure](#generated-structure)\n9. [Presets](#presets)\n10. [Development Workflow](#development-workflow)\n11. [Docker \u0026 Compose Support](#docker--compose)\n12. [polyglot.json Configuration](#polyglotjson)\n13. [Plugins](#plugins)\n14. [Basic Dev Runner](#basic-dev-runner)\n15. [Roadmap](#roadmap--ideas)\n16. [Contributing](#contributing)\n17. [License](#license)\n\n---\n\n## Why create-polyglot?\nBuilding a production-style polyglot microservice environment normally requires repetitive boilerplate across languages, Docker files, presets, and configs. `create-polyglot` automates:\n- Consistent folder layout \u0026 service naming\n- Language starter templates (Node, FastAPI, Go, Spring Boot, Next.js)\n- Optional monorepo orchestration (Turborepo or Nx) OR a zero-frills basic runner\n- Dockerfile + `compose.yaml` generation with correct port mappings\n- Extensible plugin scaffolding for future lifecycle hooks\n- A centralized manifest (`polyglot.json`) driving subsequent commands (e.g. `add service`)\n\nUse it to prototype architectures, onboard teams faster, or spin up reproducible demos / PoCs.\n\n## Features\n- 🚀 Rapid polyglot monorepo scaffolding (Node.js, Python/FastAPI, Go, Java Spring Boot, Next.js)\n- 🧩 Optional presets: Turborepo, Nx, or Basic runner\n- 🐳 Automatic Dockerfile + Docker Compose generation\n- 🛠 Interactive wizard (or fully non-interactive via flags)\n- 🔁 Post-init extensibility: add services \u0026 plugins anytime\n- 📦 Shared package (`packages/shared`) for cross-service JS utilities\n- 🧪 Vitest test setup for the CLI itself\n- 🌈 Colorized dev logs \u0026 health probing for Node/frontend services\n- 🔌 Plugin skeleton generation (`create-polyglot add plugin \u003cname\u003e`)\n- 📄 Single source of truth: `polyglot.json`\n- ✅ Safe guards: port collision checks, reserved name checks, graceful fallbacks\n- 📝 Friendly chalk-based CLI output with clear status symbols\n\n## Quick Start\nScaffold a workspace named `my-org` with multiple services:\n\n```bash\nnpx create-polyglot init my-org -s node,python,go,java,frontend --git --yes\n```\n\nThen run everything (Node + frontend locally):\n```bash\ncreate-polyglot dev\n```\n\nOr via Docker Compose:\n```bash\ncreate-polyglot dev --docker\n```\n\nAdd a new service later:\n```bash\ncreate-polyglot add service payments --type node --port 4100\n```\n\n## Installation\nGlobal (recommended for repeated use):\n```bash\nnpm install -g create-polyglot\n```\n\nLocal dev / contributing:\n```bash\nnpm install\nnpm link   # or: pnpm link --global / yarn link / bun link\n```\n\n## Usage Examples\nInteractive wizard (prompts for missing info):\n```bash\ncreate-polyglot init my-org\n```\n\nNon-interactive with explicit services \u0026 git init:\n```bash\ncreate-polyglot init my-org -s node,python,go --git --yes\n```\n\nAdd plugin skeleton:\n```bash\ncreate-polyglot add plugin postgres\n```\n\nStart dev with Docker:\n```bash\ncreate-polyglot dev --docker\n```\n\n## Commands\n| Command | Description |\n|---------|-------------|\n| `create-polyglot init \u003cname\u003e` | Scaffold a new workspace (root invocation without `init` is deprecated). |\n| `create-polyglot add service \u003cname\u003e` | Add a service after init (`--type`, `--port`, `--yes`). |\n| `create-polyglot add plugin \u003cname\u003e` | Create plugin skeleton under `plugins/\u003cname\u003e`. |\n| `create-polyglot dev [--docker]` | Run Node \u0026 frontend services locally or all via compose. |\n\n## Init Options\n| Flag | Description |\n|------|-------------|\n| `-s, --services \u003clist\u003e` | Comma separated services: `node,python,go,java,frontend` |\n| `--preset \u003cname\u003e` | `turborepo`, `nx`, or `basic` (default auto -\u003e asks) |\n| `--git` | Initialize git repo \u0026 initial commit |\n| `--no-install` | Skip dependency installation step |\n| `--package-manager \u003cpm\u003e` | One of `npm|pnpm|yarn|bun` (default: detect or npm) |\n| `--frontend-generator` | Use `create-next-app` (falls back to template on failure) |\n| `--force` | Overwrite existing target directory if it exists |\n| `--yes` | Accept defaults \u0026 suppress interactive prompts |\n\nIf you omit flags, the wizard will prompt interactively (similar to `create-next-app`).\n\n## Generated Structure\n```\nmy-org/\n  services/\n    node/          # Express + dev script\n    python/        # FastAPI + uvicorn\n    go/            # Go net/http service\n    java/          # Spring Boot (Maven)\n    frontend/      # Next.js (template or create-next-app output)\n  gateway/\n  infra/\n  packages/\n    shared/\n  plugins/         # created when adding plugins\n  compose.yaml\n  polyglot.json    # persisted configuration\n  package.json\n  turbo.json / nx.json (if preset chosen)\n  scripts/\n    dev-basic.cjs\n```\n\n### Presets\n- **Turborepo**: Generates `turbo.json`, sets root `dev` \u0026 `build` scripts for pipeline caching.\n- **Nx**: Generates `nx.json` and adjusts scripts accordingly.\n- **Basic**: Minimal setup + `scripts/dev-basic.cjs` for simple concurrency.\n\n## Development Workflow\n1. Scaffold with `init`.\n2. (Optional) Add more services or plugins.\n3. Run `create-polyglot dev` (local) or `create-polyglot dev --docker`.\n4. Edit services under `services/\u003cname\u003e`.\n5. Extend infra / databases inside `compose.yaml`.\n\n### Basic Dev Runner\nWhen no preset is chosen, `npm run dev` uses `scripts/dev-basic.cjs`:\n1. Detects package manager (pnpm \u003e yarn \u003e bun \u003e npm fallback)\n2. Scans `services/` for Node services\n3. Runs those with a `dev` script\n4. Prefixes log lines with service name\n\nNon-Node services start manually or via compose:\n```bash\ncd services/python \u0026\u0026 uvicorn app.main:app --reload\n```\n\n## polyglot dev Command\n`create-polyglot dev` reads `polyglot.json`, launches Node \u0026 frontend services that expose a `dev` script, assigns each a colorized log prefix, and probes `http://localhost:\u003cport\u003e/health` until ready (15s timeout). Pass `--docker` to instead delegate to `docker compose up --build` for all services.\n\nIf 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`.\n\n## Docker \u0026 Compose\nFor each selected service a Dockerfile is generated. A `compose.yaml` includes:\n- Service definitions with build contexts\n- Port mappings (adjust manually if conflicts)\n- Shared network `app-net`\n\nYou can extend compose with volumes, env vars, or database services after generation.\n\n## Frontend Generation\nIf `--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.\n\n## polyglot.json\nExample:\n```jsonc\n{\n  \"name\": \"my-org\",\n  \"preset\": \"none\",\n  \"packageManager\": \"npm\",\n  \"services\": [\n    { \"name\": \"node\", \"type\": \"node\", \"port\": 3001, \"path\": \"services/node\" }\n  ]\n}\n```\nUsed by `add service` to assert uniqueness and regenerate `compose.yaml`.\n\n## Plugins\n`create-polyglot add plugin \u003cname\u003e` scaffolds `plugins/\u003cname\u003e/index.js` with a hook skeleton (`afterInit`). Future releases will execute hooks automatically during lifecycle events.\n\n## Shared Package\n`packages/shared` shows cross-service Node utilities. Extend or add per-language shared modules.\n\n## Force Overwrite\nIf the target directory already exists, the CLI aborts unless `--force` is passed. Use with caution.\n\n## Git Initialization\nPass `--git` to automatically run `git init`, create an initial commit, and (if desired) you can add remotes afterwards.\n\n## Lint \u0026 Format\nGenerates ESLint + Prettier base configs at the root. Extend rules per service if needed.\n\n## Roadmap / Ideas\n- Plugin hook execution pipeline\n- Healthchecks and depends_on in `compose.yaml`\n- Additional generators (Remix, Astro, SvelteKit)\n- Automatic test harness \u0026 CI workflow template\n- Language-specific shared libs (Python package, Go module)\n- Hot reload integration aggregator\n- Remove service / remove plugin commands\n\n## Contributing\nContributions welcome! See `CONTRIBUTING.md` for guidelines. Please run tests before submitting a PR:\n```bash\nnpm test\n```\n\n## License\nMIT\n\n## Documentation Site (VitePress)\n\nLocal docs development:\n```bash\nnpm run docs:dev\n```\nBuild static site:\n```bash\nnpm run docs:build\n```\nPreview production build:\n```bash\nnpm run docs:preview\n```\nDocs source lives in `docs/` with sidebar-driven structure defined in `docs/.vitepress/config.mjs`.\n\n### Deployment\nDocs 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/`.\n\n## Installation (local dev)\n\n```bash\nnpm install\nnpm link # or: pnpm link --global / yarn link / bun link\n```\n\nThen run (non-interactive example):\n\n```bash\ncreate-polyglot init my-org -s node,python,go,java,frontend --git --yes\n```\n\nInteractive (wizard prompts for any missing info):\n\n```bash\ncreate-polyglot init my-org\n```\n\nAdd a service later:\n```bash\ncreate-polyglot add service payments --type node --port 4100\n```\n\nAdd a plugin scaffold:\n```bash\ncreate-polyglot add plugin postgres\n```\n\nRun all services in dev mode (Node \u0026 frontend locally; others manual unless using docker):\n```bash\ncreate-polyglot dev\n```\n\nRun everything via Docker Compose:\n```bash\ncreate-polyglot dev --docker\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `create-polyglot init \u003cname\u003e` | Scaffold a new workspace (root invocation without `init` is deprecated). |\n| `create-polyglot add service \u003cname\u003e` | Add a service after init (`--type`, `--port`, `--yes`). |\n| `create-polyglot add plugin \u003cname\u003e` | Create plugin skeleton under `plugins/\u003cname\u003e`. |\n| `create-polyglot dev [--docker]` | Run Node \u0026 frontend services locally or all via compose. |\n\n## Init Options\n\n| Flag | Description |\n|------|-------------|\n| `-s, --services \u003clist\u003e` | Comma separated services: `node,python,go,java,frontend` |\n| `--preset \u003cname\u003e` | `turborepo`, `nx`, or `basic` (default auto -\u003e asks) |\n| `--git` | Initialize git repo \u0026 initial commit |\n| `--no-install` | Skip dependency installation step |\n| `--package-manager \u003cpm\u003e` | One of `npm|pnpm|yarn|bun` (default: detect or npm) |\n| `--frontend-generator` | Use `create-next-app` (falls back to template on failure) |\n| `--force` | Overwrite existing target directory if it exists |\n\nIf you omit flags, the wizard will prompt interactively (similar to `create-next-app`).\n\n## Generated Structure\n```\nmy-org/\n  services/\n    node/          # Express + dev script\n    python/        # FastAPI + uvicorn\n    go/            # Go net/http service\n    java/          # Spring Boot (Maven)\n    frontend/      # Next.js (template or create-next-app output)\n  gateway/\n  infra/\n  packages/\n    shared/\n  plugins/         # created when adding plugins\n  compose.yaml\n  polyglot.json    # persisted configuration\n  package.json\n  turbo.json / nx.json (if preset chosen)\n  scripts/\n    dev-basic.cjs\n```\n\n### Presets\n- Turborepo: Generates `turbo.json`, sets root `dev` \u0026 `build` scripts to leverage Turborepo pipelines.\n- Nx: Generates `nx.json` and adjusts scripts accordingly.\n- Basic: Provides a minimal setup plus `scripts/dev-basic.cjs` for simple concurrency.\n\n### Basic Dev Runner\nWhen no preset is chosen, `npm run dev` uses `scripts/dev-basic.cjs`:\n1. Detects package manager (pnpm \u003e yarn \u003e bun \u003e npm fallback)\n2. Scans `services/` for Node services\n3. Runs those with a `dev` script\n4. Prefixes log lines with service name\n\nNon-Node services start manually or via compose:\n```\ncd services/python \u0026\u0026 uvicorn app.main:app --reload\n```\n\n### polyglot dev Command\n`create-polyglot dev` reads `polyglot.json`, launches Node \u0026 frontend services that expose a `dev` script, assigns each a colorized log prefix, and probes `http://localhost:\u003cport\u003e/health` until ready (15s timeout). Pass `--docker` to instead delegate to `docker compose up --build` for all services.\n\nIf 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`.\n\n### Docker \u0026 Compose\nFor each selected service a Dockerfile is generated. A `compose.yaml` includes:\n- Service definitions with build contexts\n- Port mappings (adjust manually if conflicts)\n- Shared network `app-net`\nYou can extend compose with volumes, env vars, or database services after generation.\n\n### Frontend Generation\nIf `--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.\n\n### polyglot.json\nExample:\n```jsonc\n{\n  \"name\": \"my-org\",\n  \"preset\": \"none\",\n  \"packageManager\": \"npm\",\n  \"services\": [\n    { \"name\": \"node\", \"type\": \"node\", \"port\": 3001, \"path\": \"services/node\" }\n  ]\n}\n```\nUsed by `add service` to assert uniqueness and regenerate `compose.yaml`.\n\n### Plugins\n`create-polyglot add plugin \u003cname\u003e` scaffolds `plugins/\u003cname\u003e/index.js` with a hook skeleton (`afterInit`). Future releases will execute hooks automatically during lifecycle events.\n\n### Shared Package\n`packages/shared` shows cross-service Node utilities. Extend or add per-language shared modules.\n\n### Force Overwrite\nIf the target directory already exists, the CLI aborts unless `--force` is passed. Use with caution.\n\n### Git Initialization\nPass `--git` to automatically run `git init`, create an initial commit, and (if desired) you can add remotes afterwards.\n\n### Lint \u0026 Format\nGenerates ESLint + Prettier base configs at the root. Extend rules per service if needed.\n\n### Roadmap / Ideas\n- Plugin hook execution pipeline\n- Healthchecks and depends_on in `compose.yaml`\n- Additional generators (Remix, Astro, SvelteKit)\n- Automatic test harness \u0026 CI workflow template\n- Language-specific shared libs (Python package, Go module)\n- Hot reload integration aggregator\n- Remove service / remove plugin commands\n\n## License\nMIT\n\n## Documentation Site (VitePress)\n\nLocal docs development:\n```bash\nnpm run docs:dev\n```\nBuild static site:\n```bash\nnpm run docs:build\n```\nPreview production build:\n```bash\nnpm run docs:preview\n```\nDocs source lives in `docs/` with sidebar-driven structure defined in `docs/.vitepress/config.mjs`.\n\n### Deployment\nDocs 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/`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaifcoder%2Fcreate-polyglot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaifcoder%2Fcreate-polyglot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaifcoder%2Fcreate-polyglot/lists"}