Monorepo Setup

A monorepo stores multiple related projects in a single repository, a common practice for managing interconnected projects like web applications and their APIs.

This guide shows you how to efficiently set up a monorepo with oRPC while maintaining end-to-end type safety across all projects.

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. This ensures the client can resolve all types used by oRPC procedures while also improving TypeScript performance.

{
  "compilerOptions": {
    // ...
  },
  "references": [
    { "path": "../server" } 
  ]
}

{
  "compilerOptions": {
    "composite": true
    // ...
  }
}

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.

apps/
├─ api/    // Import `core-contract` and implement it
├─ web/    // Import `core-contract` and set up @orpc/client here
├─ app/
packages/
├─ core-contract/  // Define contract with @orpc/contract
├─ .../

apps/
├─ api/    // Import `core-service` and run it in your environment
├─ web/    // Import `core-service` and set up @orpc/client here
├─ app/
packages/
├─ core-service/   // Define procedures with @orpc/server
├─ .../

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
├─ .../

Learn More

• Scaling Large Projects
• Publish Client to NPM