docs: Multiservice Monorepo Playground (#1209)

Fixes #1018

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Updated monorepo setup best practices guide with improved organization
and clarity.
* Added new Multiservice Monorepo Playground with local development
setup instructions and examples.
* Enhanced documentation sections with clearer recommendations, tip
blocks, and illustrative code examples demonstrating hybrid
architectures.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

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

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