SSR optimizations with separate api app in turborepo

[vinkovsky]

Hello! I’m using oRPC with Turborepo. The main server lives in the api folder, and the client is in the web folder under apps. Contracts are hosted in packages. So my structure looks like this:

├── apps
│   ├── api
│   └── web
├── packages
│   ├── db
│   ├── shared-client
│   ├── shared-web
│   ├── typescript-config
│   └── ui
└── turbo.json

I would like to know how to make the setup described here work in this structure: https://orpc.unnoq.com/docs/best-practices/optimize-ssr#conceptual-approach

[unnoq]

This setup require api and web in the same server. If you don't know how I don't think I can help eighter.

[dosubot[bot]]

You can adapt the oRPC SSR optimization pattern to your Turborepo setup by following these steps:

1. In your web app, create a lib/orpc.server.ts that initializes the server-side oRPC client using createRouterClient and assigns it to globalThis.$client. Only import server-only dependencies here, and use 'server-only' at the top to ensure it's never bundled into the client. If you need per-request context (like headers for authentication), provide it via the context option, but only include data that's safe to share globally or use middleware for per-request data (example).

2. Import lib/orpc.server.ts as early as possible in your server entrypoints (e.g., app/layout.tsx or instrumentation.ts) to ensure the server client is initialized before any SSR logic runs (reference).

3. In your shared client module (e.g., lib/orpc.ts), export a client that uses globalThis.$client if available (SSR), or falls back to a client-side oRPC client (CSR) using createORPCClient with an RPCLink to your API route. Never statically import server-only code in this file—keep all server logic in orpc.server.ts (details).

4. In your api app, expose your oRPC router at an endpoint like /api/rpc using RPCHandler or OpenAPIHandler, and ensure both api and web import the same router or contract from a shared package in packages/ for type safety and code reuse (monorepo structure).

5. Use TypeScript project references and avoid alias imports—link shared packages via your workspace manager (e.g., pnpm workspaces) to prevent module duplication and type mismatches.

6. Watch out for static imports of server-only modules in shared files, which can break SSR in frameworks like Next.js or TanStack Start. Always split server/client logic into separate files and use dynamic imports or runtime guards if needed (pitfall explanation).

7. If you use authentication or need to forward headers for SSR, generate headers per request and only forward safe headers (like cookies or authorization) to avoid leaking sensitive data or causing caching issues (header handling).

This pattern lets your SSR logic call API procedures directly (no HTTP roundtrip), while keeping a clean separation between server and client code. If you run into issues with error handling (e.g., instanceof checks failing), check for module duplication in your monorepo and consider using custom error guards (error pitfall).

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[vinkovsky]

Thank you for your reply! Both the api and web applications will run on the same physical server (same Node.js environment, separate Docker containers). I’m not asking about deployment details, but rather about the recommended way to wire things up with oRPC in this Turborepo layout.

[vinkovsky]

My setup is actually very similar to the one in this example repo: https://github.com/unnoq/orpc-multiservice-monorepo-playground/tree/main. In the example repo I didn’t see the specific wiring related to the optimize-ssr approach, so I was hoping for a small code pointer or recommendation on where you would put that SSR optimization code in a monorepo like this.

[unnoq]

@vinkovsky To clarify, this setup requires the client and server to run in the same process, same Node.js instance, same port, same container, etc. I was really surprised when you asked about using this setup with separate Docker containers.

[vinkovsky]

@unnoq Thanks a lot for clarifying this. That’s where the misunderstanding came from