From 1632a24d0f8a07bf7a8a1815605e57695429b9dc Mon Sep 17 00:00:00 2001 From: intech Date: Mon, 20 Jul 2026 00:04:09 +0400 Subject: [PATCH 1/2] docs: scaffolding guide for `connectum init` / `generate service` - new guide page en/guide/scaffolding.md (init flow, options table, interceptor order, generate service, the add-a-service recipe) + sidebar entry after Quickstart - cli-commands.md: point to the scaffolding guide for the published @connectum/cli tool - runtime-compatibility.md: note the Bun caveats are narrow (client transport) and that scaffolding emits Bun-appropriate defaults; restate the Node floor (raw .ts >=25.2 vs tsx/compiled >=22.13) Companion docs for the connectum cli-scaffolding change (Phase 4, tasks 4.1-4.3). Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01SdapMMJeamn5TDrY8yzHRQ --- .vitepress/config/en.ts | 1 + en/contributing/cli-commands.md | 11 ++++ en/guide/runtime-compatibility.md | 9 +++ en/guide/scaffolding.md | 106 ++++++++++++++++++++++++++++++ 4 files changed, 127 insertions(+) create mode 100644 en/guide/scaffolding.md diff --git a/.vitepress/config/en.ts b/.vitepress/config/en.ts index 42ce1c17..c00b3882 100644 --- a/.vitepress/config/en.ts +++ b/.vitepress/config/en.ts @@ -7,6 +7,7 @@ const guideSidebar: DefaultTheme.SidebarItem[] = [ items: [ { text: 'About Connectum', link: '/en/guide/about' }, { text: 'Quickstart', link: '/en/guide/quickstart' }, + { text: 'Scaffolding a Service', link: '/en/guide/scaffolding' }, { text: 'Architecture Overview', link: '/en/guide/production/architecture' }, { text: 'Runtime Compatibility', link: '/en/guide/runtime-compatibility' }, ], diff --git a/en/contributing/cli-commands.md b/en/contributing/cli-commands.md index 7d9285a2..9925949d 100644 --- a/en/contributing/cli-commands.md +++ b/en/contributing/cli-commands.md @@ -4,6 +4,17 @@ Complete reference of CLI commands for working with the Connectum monorepo. +::: tip The `connectum` CLI +This page covers the monorepo development scripts. The published `@connectum/cli` tool +(`connectum init`, `connectum generate service`, `connectum proto sync`) is documented +in [Scaffolding a New Service](/en/guide/scaffolding). In short: + +```bash +npx @connectum/cli init my-service # scaffold a new project +npx @connectum/cli generate service x # add a service to an existing project +``` +::: + ## Prerequisites - **Node.js**: >=25.2.0 (for development), >=22.13.0 (for consumers) diff --git a/en/guide/runtime-compatibility.md b/en/guide/runtime-compatibility.md index 4a72d523..d8643ded 100644 --- a/en/guide/runtime-compatibility.md +++ b/en/guide/runtime-compatibility.md @@ -6,6 +6,15 @@ outline: deep Connectum targets **Node.js 22+** as the primary runtime. Bun compatibility is a secondary goal -- most packages work, but some features require workarounds or have known limitations. This page documents the current state of runtime compatibility across all `@connectum/*` packages. +::: tip Scaffolding picks the right defaults +The Bun limitations below are narrow — they affect the HTTP/2 **client** transport, not +the server. `connectum init --runtime bun` (see [Scaffolding a Service](/en/guide/scaffolding)) +already emits Bun-appropriate defaults (the `bun test` runner and the in-process +`createLocalClient` test transport), so a scaffolded Bun project sidesteps them. The +Node floor also depends on how you run your source: raw `.ts` needs Node ≥25.2, while the +`tsx` / compiled path runs on Node ≥22.13. +::: + ## Compatibility Matrix | Package | Node.js 22 | Node.js 25 | Bun | diff --git a/en/guide/scaffolding.md b/en/guide/scaffolding.md new file mode 100644 index 00000000..3eaefb99 --- /dev/null +++ b/en/guide/scaffolding.md @@ -0,0 +1,106 @@ +# Scaffolding a New Service + +The `connectum` CLI scaffolds a production-ready Connectum project and adds services to +an existing one. It fetches the dogfooded `getting-started` example as the base (so the +starter layout is always in sync with a tested example) and composes the modules you +select on top. + +::: tip Requirements +`connectum init` fetches the base from GitHub, so it needs network access the first +time. It produces a standalone project that depends on the published `@connectum/*` +packages. +::: + +## `connectum init` + +Create a new project. Run it interactively: + +```bash +npx @connectum/cli init +# or: pnpm dlx @connectum/cli init +``` + +The wizard asks for a project name, runtime, package manager, and which modules to +include. Or pass everything as flags for a non-interactive run: + +```bash +npx @connectum/cli init payments \ + --package-manager pnpm \ + --otel \ + --events nats \ + --auth \ + --yes +``` + +Then: + +```bash +cd payments +pnpm install +pnpm run start +``` + +`buf generate` is wired into the `start`, `test`, and `typecheck` scripts, so the +generated code under `gen/` is always current — you never hit a "cannot find module +`#gen/...`" wall. + +### Options + +| Flag | Values | Description | +|------|--------|-------------| +| `--runtime` | `node` (default), `bun` | Target runtime | +| `--package-manager` | `pnpm` (default), `npm` | Package manager | +| `--node-exec` | `raw` (default), `tsx` | Node execution model: `raw` runs `.ts` directly (Node ≥25.2); `tsx` compiles (Node ≥22.13) | +| `--otel` | — | Add OpenTelemetry (interceptor + provider lifecycle) | +| `--events` | `nats`, `kafka`, `redpanda`, `redis`, `amqp` | Add an EventBus with the chosen adapter | +| `--auth` | — | Add JWT authentication + proto-driven authorization | +| `--catalog` | — | Add the service catalog (typed `ctx.call` / `ctx.stream`) | +| `--resilience` | comma list of `timeout,bulkhead,circuitBreaker,retry,fallback` | Enable resilience interceptors | +| `--healthcheck` / `--no-healthcheck` | — | Include the gRPC health protocol (default on) | +| `--reflection` / `--no-reflection` | — | Include gRPC server reflection (default on) | +| `--sample` / `--no-sample` | — | Emit the runnable sample Greeter service (default on) | +| `--yes`, `-y` | — | Non-interactive; use flags and defaults | +| `--force` | — | Overwrite existing files | + +### Interceptor order + +When multiple interceptor-adding modules are selected, `init` emits a single, consistent +order (outermost → innermost): **OpenTelemetry → error handler → auth → validation → +resilience → your custom interceptors**. OpenTelemetry is outermost so a span always +covers the whole request, including errors. + +## `connectum generate service` + +Add a service to an existing project: + +```bash +npx @connectum/cli generate service billing +# with an event handler too: +npx @connectum/cli generate service inventory --with-events +``` + +This scaffolds: + +- `proto//v1/.proto` — a starter service (and, with `--with-events`, an + event-handler service annotated with a topic); +- `src/services/Service.ts` — a `defineService` skeleton whose rpc handlers throw + `Code.Unimplemented` until you implement them (and, with `--with-events`, an + `EventRoute` with an ack-by-default handler). + +It never edits your `src/server.ts` (that file is yours). Instead it prints the exact +registration to add: + +```text +Register the new service in src/server.ts: + import { billingService } from "#services/billingService.ts"; + // add billingService to the services: [...] array passed to createServer +``` + +## Adding a service by hand + +The one-shot commands are conveniences — the underlying loop is small: + +1. Add a `proto//v1/.proto`. +2. Run `buf generate` (or just `pnpm run test` / `start` — it runs first). +3. Write `defineService(MyService, { ... })` in `src/services/`. +4. Register it in the `services: [...]` array in `src/server.ts`. From 62601730efca5d2f620f64c3bb1a4cadef00d0f1 Mon Sep 17 00:00:00 2001 From: intech Date: Tue, 21 Jul 2026 08:49:20 +0400 Subject: [PATCH 2/2] docs: align the scaffolding guide with the merged runtime switcher MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rebased onto main after the runtime-switcher PR landed, and corrected content that it made stale: - `runtime-compatibility.md`: my earlier tip claimed the Bun limitations were "narrow — the HTTP/2 client transport". That is no longer true: main now documents that Bun >= 1.2.6 needs no special client code. The tip now only states what still holds — `init --runtime bun` emits Bun-appropriate defaults — and adds the newly documented guidance that the CLI is exercised on Node.js, so it should be run with `npx` even in a Bun project. - `scaffolding.md`: same `npx` note in Requirements, plus the generated `start`/`test` scripts are now shown through the `::: runtime` switcher (Node | Bun) instead of prose, and it is stated that the generated e2e test is runtime-agnostic (in-process `createLocalClient`, no socket). `vitepress build` passes; the built page contains both switcher branches. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01SdapMMJeamn5TDrY8yzHRQ --- en/guide/runtime-compatibility.md | 12 +++++------- en/guide/scaffolding.md | 17 ++++++++++++++++- 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/en/guide/runtime-compatibility.md b/en/guide/runtime-compatibility.md index bc2179ad..4a0af89d 100644 --- a/en/guide/runtime-compatibility.md +++ b/en/guide/runtime-compatibility.md @@ -14,13 +14,11 @@ navigation bar (and next to each affected block). This page deliberately shows b runtimes side by side. ::: -::: tip Scaffolding picks the right defaults -The Bun limitations below are narrow — they affect the HTTP/2 **client** transport, not -the server. `connectum init --runtime bun` (see [Scaffolding a Service](/en/guide/scaffolding)) -already emits Bun-appropriate defaults (the `bun test` runner and the in-process -`createLocalClient` test transport), so a scaffolded Bun project sidesteps them. The -Node floor also depends on how you run your source: raw `.ts` needs Node ≥25.2, while the -`tsx` / compiled path runs on Node ≥22.13. +::: tip Scaffolding emits runtime-appropriate defaults +`connectum init --runtime bun` (see [Scaffolding a Service](/en/guide/scaffolding)) emits +Bun-appropriate defaults — the `bun test` runner and the in-process `createLocalClient` +test transport, which opens no socket and behaves identically on both runtimes. The CLI +itself is exercised on Node.js, so run it with `npx` even inside a Bun project. ::: ## Compatibility Matrix diff --git a/en/guide/scaffolding.md b/en/guide/scaffolding.md index 3eaefb99..bfce55a8 100644 --- a/en/guide/scaffolding.md +++ b/en/guide/scaffolding.md @@ -8,7 +8,8 @@ select on top. ::: tip Requirements `connectum init` fetches the base from GitHub, so it needs network access the first time. It produces a standalone project that depends on the published `@connectum/*` -packages. +packages. The CLI itself is exercised on Node.js — run it with `npx` even when the +project you are scaffolding targets Bun. ::: ## `connectum init` @@ -44,6 +45,20 @@ pnpm run start generated code under `gen/` is always current — you never hit a "cannot find module `#gen/...`" wall. +The generated scripts match the runtime you picked: + +::: runtime +== node +- `start` — `buf generate && node src/index.ts` (raw `.ts` execution; Node >= 25.2, or `tsx` on Node >= 22.13) +- `test` — `buf generate && node --test tests/**/*.test.ts` +== bun +- `start` — `buf generate && bun src/index.ts` +- `test` — `buf generate && bun test tests/` +::: + +The generated e2e test itself is runtime-agnostic: it uses the in-process +`createLocalClient`, which opens no socket and behaves identically on both runtimes. + ### Options | Flag | Values | Description |