Monorepo Setup

Set up a monorepo with oRPC using TypeScript project references to keep end-to-end type safety across interconnected apps and packages.

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
    // ...
  }
}

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:

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.

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

Monorepo Setup

TypeScript Project References

Recommended Structure

Learn More