From 1c490062260c8b32ab56ed4bd5672cca3af2e2de Mon Sep 17 00:00:00 2001 From: unnoq Date: Wed, 12 Nov 2025 14:52:57 +0700 Subject: [PATCH] docs: Multiservice Monorepo Playground Fixes #1018 --- .../docs/best-practices/monorepo-setup.md | 35 +++++++++++++------ apps/content/docs/playgrounds.md | 2 ++ 2 files changed, 27 insertions(+), 10 deletions(-) diff --git a/apps/content/docs/best-practices/monorepo-setup.md b/apps/content/docs/best-practices/monorepo-setup.md index 2f7070efa..109a5ac76 100644 --- a/apps/content/docs/best-practices/monorepo-setup.md +++ b/apps/content/docs/best-practices/monorepo-setup.md @@ -9,6 +9,10 @@ A monorepo stores multiple related projects in a single repository, a common pra This guide shows you how to efficiently set up a monorepo with oRPC while maintaining end-to-end type safety across all projects. +::: info Playground +Explore a sample monorepo setup in our [Multiservice Monorepo Playground](https://github.com/unnoq/orpc-multiservice-monorepo-playground). +::: + ## TypeScript Project References When consuming, some parts of the client may end up being typed as `any` because the client environment doesn't have access to all types that oRPC procedures depend on. The most effective solution is to use [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html). This ensures the client can resolve all types used by oRPC procedures while also improving TypeScript performance. @@ -37,14 +41,7 @@ When consuming, some parts of the client may end up being typed as `any` because ::: -## Recommended Structure - -- `/apps`: `references` dependencies in `tsconfig.json` -- `/packages`: Enable `composite` in `tsconfig.json` - -The key principle is separating the server component (with `composite` enabled) into a dedicated package containing only necessary files. This approach simplifies dealing with the `composite` option's constraints. - -::: details Common `composite` option's constraint +::: tip Common `composite` option's constraint The most common issue with `composite` is missing type definitions, resulting in: `The inferred type of "X" cannot be named without a reference to "Y". This is likely not portable. A type annotation is necessary.` If you encounter this, try installing package `Y` if not already installed and adding this to your codebase where the error occurs: @@ -55,13 +52,20 @@ import type * as _A from '../../node_modules/detail_Y_path_here' ::: +## Recommended Structure + +- `/apps`: `references` dependencies in `tsconfig.json` +- `/packages`: Enable `composite` in `tsconfig.json` + +The key principle is separating the server component (with `composite` enabled) into a dedicated package containing only necessary files. This approach simplifies dealing with the `composite` option's constraints. + ::: tip Avoid **alias imports** inside server components when possible. Instead, use **linked workspace packages** (e.g., [PNPM Workspace protocol](https://pnpm.io/workspaces#workspace-protocol-workspace)). ::: ::: code-group -```txt [contract-first] +```txt [Contract First] apps/ ├─ api/ // Import `core-contract` and implement it ├─ web/ // Import `core-contract` and set up @orpc/client here @@ -71,7 +75,7 @@ packages/ ├─ .../ ``` -```txt [normal] +```txt [Service First] apps/ ├─ api/ // Import `core-service` and run it in your environment ├─ web/ // Import `core-service` and set up @orpc/client here @@ -81,6 +85,17 @@ packages/ ├─ .../ ``` +```txt [Hybrid] +apps/ +├─ api/ // Import `core-service` and set up @orpc/server here +├─ web/ // Import `core-contract` and set up @orpc/client here +├─ app/ +packages/ +├─ core-contract/ // Define contract with @orpc/contract +├─ core-service/ // Import `core-contract` and implement it +├─ .../ +``` + ::: ::: info diff --git a/apps/content/docs/playgrounds.md b/apps/content/docs/playgrounds.md index 228bbfc1e..d7d13d3f1 100644 --- a/apps/content/docs/playgrounds.md +++ b/apps/content/docs/playgrounds.md @@ -24,6 +24,7 @@ featuring pre-configured examples accessible instantly via StackBlitz or local s | Bun WebSocket + OpenTelemetry | | [View Source](https://github.com/unnoq/orpc/tree/main/playgrounds/bun-websocket-otel) | | Electron Playground | | [View Source](https://github.com/unnoq/orpc/tree/main/playgrounds/electron) | | Browser Extension Playground | | [View Source](https://github.com/unnoq/orpc/tree/main/playgrounds/browser-extension) | +| Multiservice Monorepo Playground | | [View Source](https://github.com/unnoq/orpc-multiservice-monorepo-playground) | | Vue + Bun + Monorepo (Community) | | [View Source](https://github.com/hunterwilhelm/orpc-community-playgrounds/tree/main/vue-bun) | :::warning @@ -47,6 +48,7 @@ npx degit unnoq/orpc/playgrounds/cloudflare-worker orpc-cloudflare-worker-playgr npx degit unnoq/orpc/playgrounds/bun-websocket-otel orpc-bun-websocket-otel-playground npx degit unnoq/orpc/playgrounds/electron orpc-electron-playground npx degit unnoq/orpc/playgrounds/browser-extension orpc-browser-extension-playground +npx degit unnoq/orpc-multiservice-monorepo-playground orpc-multiservice-monorepo-playground # Community (clone at your own risk) npx degit hunterwilhelm/orpc-community-playgrounds/vue-bun orpc-vue-bun-monorepo-playground