Skip to content

Commit 0525df0

Browse files
kaifcoderkaifcoder
committed
Add VitePress for documentation generation and update scripts in package.json
Signed-off-by: kaifcoder <kaifmohd2014@gmail.com>
1 parent 0c9d5b6 commit 0525df0

File tree

19 files changed

+1872
-8
lines changed

19 files changed

+1872
-8
lines changed

‎.copilot/tasks.json‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
{
2+
"version": "1.0.0",
3+
"name": "Create Polyglot Framework Tasks",
4+
"description": "Task plan for developing the create-polyglot CLI framework for polyglot microservices.",
5+
"tasks": [
6+
{
7+
"id": "init-cli",
8+
"title": "Initialize CLI Project Structure",
9+
"description": "Set up the Node.js CLI using oclif or Commander. Add basic command parsing and help menus.",
10+
"steps": [
11+
"Run `npm init -y` and install dependencies (`commander`, `execa`, `chalk`, `inquirer`).",
12+
"Set up `bin/create-polyglot.js` entry point.",
13+
"Implement the CLI banner and basic help text.",
14+
"Add version and --help flags."
15+
]
16+
},
17+
{
18+
"id": "add-init-command",
19+
"title": "Implement `init` Command",
20+
"description": "Scaffold a new polyglot monorepo structure.",
21+
"steps": [
22+
"Add `polyglot init` command to create folder structure `/services`, `/gateway`, `/infra`.",
23+
"Generate a base README.md and polyglot.json config file.",
24+
"Prompt user for project name and default languages."
25+
]
26+
},
27+
{
28+
"id": "add-service-command",
29+
"title": "Implement `add service` Command",
30+
"description": "Generate new microservice boilerplate based on selected language and framework.",
31+
"steps": [
32+
"Add `polyglot add service <name> --lang <language> --framework <framework>` command.",
33+
"Copy templates from `/templates/{language}-{framework}`.",
34+
"Inject service metadata into `polyglot.json`.",
35+
"Generate Dockerfile and add service entry in `docker-compose.yml`."
36+
]
37+
},
38+
{
39+
"id": "add-dev-command",
40+
"title": "Implement `polyglot dev` Command",
41+
"description": "Run all microservices concurrently using Docker Compose or concurrently package.",
42+
"steps": [
43+
"Add `polyglot dev` command to spin up all services.",
44+
"Show colored logs for each service (use chalk or pino-pretty).",
45+
"Detect health endpoints automatically."
46+
]
47+
},
48+
{
49+
"id": "add-plugin-system",
50+
"title": "Add Plugin System",
51+
"description": "Implement plugin-based architecture for extensibility.",
52+
"steps": [
53+
"Design plugin interface (install scripts, templates, hooks).",
54+
"Add `polyglot add plugin <name>` command.",
55+
"Create official plugins for Postgres, Kafka, and Auth."
56+
]
57+
},
58+
{
59+
"id": "template-examples",
60+
"title": "Add Template Examples",
61+
"description": "Provide ready-to-run templates for common frameworks.",
62+
"steps": [
63+
"Add Node/Express, Python/FastAPI, Java/Spring Boot templates under /templates.",
64+
"Each should include minimal code + Dockerfile + README.",
65+
"Test generation for all combinations."
66+
]
67+
},
68+
{
69+
"id": "setup-ci",
70+
"title": "Setup GitHub CI for Testing & Build",
71+
"description": "Add GitHub Actions to test and build the CLI automatically.",
72+
"steps": [
73+
"Add `.github/workflows/test.yml` for lint + test + build.",
74+
"Run `npm test` on PRs.",
75+
"Publish new versions automatically to npm when tagged."
76+
]
77+
},
78+
{
79+
"id": "docs-and-readme",
80+
"title": "Add Documentation & README",
81+
"description": "Create compelling documentation for create-polyglot.",
82+
"steps": [
83+
"Write detailed README with examples and diagrams.",
84+
"Add CONTRIBUTING.md and templates for issues/PRs.",
85+
"Prepare docs site using Docusaurus or VitePress."
86+
]
87+
},
88+
{
89+
"id": "release-v1",
90+
"title": "Prepare v1.0 Release",
91+
"description": "Finalize and publish the first stable version.",
92+
"steps": [
93+
"Test all commands end-to-end.",
94+
"Bump version to 1.0.0.",
95+
"Publish to npm (`npm publish`).",
96+
"Announce release on GitHub, Reddit, and ProductHunt."
97+
]
98+
}
99+
]
100+
}

‎README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,3 +116,19 @@ Generates ESLint + Prettier base configs at the root. Extend rules per service i
116116

117117
## License
118118
MIT
119+
120+
## Documentation Site (VitePress)
121+
122+
Local docs development:
123+
```bash
124+
npm run docs:dev
125+
```
126+
Build static site:
127+
```bash
128+
npm run docs:build
129+
```
130+
Preview production build:
131+
```bash
132+
npm run docs:preview
133+
```
134+
Docs source lives in `docs/` with sidebar-driven structure defined in `docs/.vitepress/config.mjs`.

‎docs/.vitepress/config.mjs‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import { defineConfig } from 'vitepress';
2+
3+
export default defineConfig({
4+
title: 'create-polyglot',
5+
description: 'Scaffold polyglot microservice monorepos (Node, Python, Go, Java, Next.js)',
6+
head: [
7+
['meta', { name: 'theme-color', content: '#3e62ad' }],
8+
['meta', { name: 'og:title', content: 'create-polyglot' }],
9+
['meta', { name: 'og:description', content: 'Polyglot monorepo scaffolder CLI' }]
10+
],
11+
themeConfig: {
12+
nav: [
13+
{ text: 'Guide', link: '/guide/' },
14+
{ text: 'CLI', link: '/cli/' },
15+
{ text: 'Templates', link: '/templates/' }
16+
],
17+
sidebar: {
18+
'/guide/': [
19+
{ text: 'Introduction', link: '/guide/' },
20+
{ text: 'Getting Started', link: '/guide/getting-started' },
21+
{ text: 'Presets', link: '/guide/presets' },
22+
{ text: 'Docker & Compose', link: '/guide/docker' },
23+
{ text: 'Extending (New Service)', link: '/guide/extending-service' }
24+
],
25+
'/cli/': [
26+
{ text: 'Usage', link: '/cli/' },
27+
{ text: 'Flags', link: '/cli/flags' }
28+
],
29+
'/templates/': [
30+
{ text: 'Overview', link: '/templates/' },
31+
{ text: 'Node', link: '/templates/node' },
32+
{ text: 'Python', link: '/templates/python' },
33+
{ text: 'Go', link: '/templates/go' },
34+
{ text: 'Java (Spring Boot)', link: '/templates/java' },
35+
{ text: 'Frontend (Next.js)', link: '/templates/frontend' }
36+
]
37+
},
38+
socialLinks: [
39+
{ icon: 'github', link: 'https://github.com/kaifcoder/create-polyglot' }
40+
],
41+
footer: {
42+
message: 'MIT Licensed',
43+
copyright: `© ${new Date().getFullYear()} create-polyglot`
44+
}
45+
}
46+
});

‎docs/cli/flags.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Flags
2+
3+
| Flag | Description |
4+
| ---- | ----------- |
5+
| `-s, --services <list>` | Comma separated services (`node,python,go,java,frontend`). Supports `type:name:port` triples. |
6+
| `--preset <name>` | `turborepo`, `nx`, or none. Alters dev script + config file. |
7+
| `--no-install` | Skip root dependency installation step. |
8+
| `--git` | Initialize git repo & initial commit. |
9+
| `--force` | Overwrite non-empty target directory. |
10+
| `--package-manager <pm>` | `npm|pnpm|yarn|bun` (default detection or npm). |
11+
| `--frontend-generator` | Use `create-next-app` for the frontend instead of template (fallback on failure). |
12+
| `--yes` | Non-interactive defaults (project: `app`, services: `node`). |
13+
14+
Defaults when `--yes` provided and flag not explicitly set:
15+
```
16+
projectName=app
17+
services=node
18+
preset=none
19+
packageManager=npm
20+
git=false
21+
```

‎docs/cli/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# CLI Usage
2+
3+
Basic usage:
4+
```bash
5+
create-polyglot <project-name> [options]
6+
```
7+
If `<project-name>` is omitted you will be prompted.
8+
9+
Example:
10+
```bash
11+
create-polyglot my-org -s node,python --preset turborepo --git
12+
```

‎docs/guide/docker.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Docker & Compose
2+
3+
Each selected service gets a Dockerfile (if not already present). A `compose.yaml` is generated with:
4+
5+
- 1:1 service definitions
6+
- Matching internal/external port mappings
7+
- Shared network `app-net`
8+
9+
Extend compose after generation with databases, volumes, or env vars as needed.

‎docs/guide/extending-service.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Extending: New Service Type
2+
3+
To add a new service:
4+
5+
1. Create a template folder under `templates/<service>` with minimal runnable code + README (optional).
6+
2. Update `allServiceChoices` in `bin/index.js` to include the new type.
7+
3. Add a default port in `defaultPorts` map.
8+
4. Add Dockerfile generation logic inside the service loop (match existing patterns).
9+
5. Add compose entry fields if needed (environment variables, healthchecks in future).
10+
6. Update docs & tests (`tests/smoke.test.js`) to include the new service.
11+
12+
Validate by scaffolding a test project and confirming:
13+
- Dockerfile exists
14+
- Port is unique / not colliding
15+
- Service appears in summary table

‎docs/guide/getting-started.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Getting Started
2+
3+
## Install
4+
```bash
5+
npm install -g create-polyglot
6+
```
7+
8+
## Scaffold a Project
9+
```bash
10+
create-polyglot my-org -s node,python,go,java,frontend --git
11+
```
12+
If you omit flags, the wizard prompts for missing values.
13+
14+
## Directory Layout
15+
```
16+
my-org/
17+
apps/
18+
node/ python/ go/ java/ frontend/
19+
packages/shared
20+
compose.yaml
21+
package.json
22+
```
23+
24+
## Dev Workflow
25+
```bash
26+
cd my-org
27+
npm run dev # starts Node-based dev scripts (basic or preset orchestration)
28+
```
29+
Non-Node services (Python/Go/Java) start manually or via Docker compose:
30+
```bash
31+
docker compose up --build
32+
```

‎docs/guide/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Introduction
2+
3+
`create-polyglot` is a CLI that scaffolds a polyglot microservice monorepo including:
4+
5+
- Node.js (Express)
6+
- Python (FastAPI)
7+
- Go (net/http)
8+
- Java (Spring Boot)
9+
- Next.js frontend
10+
11+
It produces a workspace with `apps/*` services, optional Turborepo or Nx presets, and a basic dev runner when no preset is chosen.

‎docs/guide/presets.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Presets
2+
3+
You can select a preset via `--preset turborepo` or `--preset nx`.
4+
5+
| Preset | Effect |
6+
| ------ | ------ |
7+
| (none) | Adds `scripts/dev-basic.cjs` and uses a simple concurrent runner |
8+
| turborepo | Adds `turbo.json` and sets `dev` script to `turbo run dev --parallel` |
9+
| nx | Adds `nx.json` and sets `dev` script to `nx run-many -t dev --all` |
10+
11+
All presets share the same templates; only orchestration & caching strategies differ.

0 commit comments

Comments
 (0)