civitai__civitai/docs/trpc-router-dev-recompile-and-v11-notes.md

# tRPC route dev-recompile bottleneck — findings & tRPC v11 upgrade notes

> Context for whoever picks up the **tRPC v10 → v11 upgrade**. This summarizes a
> session that investigated slow `next dev` recompiles and prototyped a fix.
> Self-contained — no prior context needed.

## TL;DR

- **Symptom:** editing *any* file under `src/server/services/*` triggers a recompile of
  the entire `/api/trpc/[trpc]` route — **~6,255 modules, ~21s cold / ~8.8s warm route
  rebuild** — because `pages/api/trpc/[trpc].ts` → `appRouter` (`src/server/routers/index.ts`)
  **statically imports all ~93 routers → all their services** into one compilation unit.
- **Root cause is architectural, not zod/schema init.** (85 schema files / ~1,110 zod
  constructors were measured as a non-factor — zod construction is cheap.)
- **The clean fix is tRPC v11 lazy routers** (`router.lazy(() => import('./x.router'))`), one
  line per router in `index.ts`. This defers each router + its service subgraph into its own
  chunk, so editing a service only rebuilds that chunk, not the whole route.
- **We proved the mechanism works** by manually lazy-loading one service in v10 (see below),
  then **reverted it** — manual per-service `await import()` is too invasive for full coverage
  and the real win is the v11 router-level version.

## What was verified (v10 manual prototype)

We converted every importer of `generation.service.ts` (router + controllers + services it's
reached through) from static imports to lazy `await import('...generation.service')` at call
sites. Result, confirmed in dev logs:

| Edited file | `Compiling /api/trpc/[trpc]` line? | Meaning |
|---|---|---|
| `generation.service.ts` (converted → lazy) | **absent** | detached from route's eager graph ✅ |
| `image.service.ts` (unconverted → eager) | **present** (`✓ in 8.8s`) | still wired into the route |

**Diagnostic signature** (use this to verify any detachment): edit the service on a *warm*
server. If **no `○ Compiling /api/trpc/[trpc]`** line appears, it's detached.

## Caveats — read these before the v11 upgrade

### 1. ⚠️ Lazy-loading reorders module evaluation → can EXPOSE latent circular deps
This is the biggest risk for the v11 upgrade. Switching routers to `lazy()` changes which
module first triggers a given dependency cluster's evaluation. A cluster with a **pre-existing
circular import** that only worked due to a lucky eval order will start throwing at runtime:

```
TypeError: Cannot read properties of undefined (reading 'optional' | 'union' | ...)
```
…at **module-top-level** schema / `DataGraph` construction.

We hit exactly this: detaching `generation.service` surfaced a latent cycle in the data-graph:
`src/shared/data-graph/generation/*-graph.ts → common.ts → config/index → config/workflows.ts → *-graph.ts`
(`config/workflows.ts` imported version-id constants *from* the graph files, while the graphs
import helpers *back* from it — a bidirectional edge).

**Because v11 lazy routers shift the eval order of *every* router, expect MORE of these to
surface across the whole codebase, not just the data-graph.** Plan for a cycle-fixing pass.

**Mitigations / fix patterns:**
- **Enable the circular-dependency plugin first.** `next.config.mjs` already contains a
  commented-out `circular-dependency-plugin` block; run with `CIRCULAR_DEPENDENCY_PLUGIN=true`
  to map cycles at build time *before* they bite at runtime. Do this up front.
- **Break bidirectional edges by extracting shared leaf values** (constants, schemas, enums)
  into zero-import leaf modules. Example fix from this session: moved `klingVersionIds` /
  `nanoBananaVersionIds` / `viduVersionIds` out of the `*-graph.ts` files into a new leaf
  `src/shared/data-graph/generation/version-ids.ts`; both the graphs and `config/workflows.ts`
  import the leaf → edge becomes one-directional. (Graph files re-export the consts so existing
  handler imports keep working.)
- **Import leaf schemas from their source, not via a big module's re-export.** `kling-graph`
  imported `imageValueSchema` through `common.ts`'s re-export (`common` is in the cycle); fixed
  by importing directly from the leaf `media-schemas.ts`.

### 2. The re-seal floor — lazy routers won't make dev recompiles instant
Next.js webpack dev **re-seals the entire server compilation on any server edit** (you'll see a
bare `Compiled in Xs (N modules)` with *no* route name). There's an irreducible floor
(~4.4s warm in this codebase) regardless of how few modules changed. Lazy-loading removes the
*extra route rebuild* on top of the floor (the 8.8s), not the floor itself. Set expectations:
v11 lazy routers reduce per-edit cost meaningfully but don't eliminate it. If the floor itself
becomes the bottleneck, that's the point to revisit Turbopack (different incremental engine, no
re-seal) — see §4.

### 3. The `(N modules)` count in dev logs is NOT a per-edit delta
It's the **total** module count of the current compilation, and it grows as you visit more
pages in a session. Two recompiles showing `6255` vs `11888` modules are **not comparable** if
you've loaded different pages in between. To compare, hold session state constant and use
**(a)** presence/absence of the `Compiling /api/trpc/[trpc]` line and **(b)** wall-clock time.

### 4. Turbopack was explored and parked (alternative path, not pursued)
`next dev --turbo` on this repo boots but hits a series of incompatibilities. If revisited,
the known blockers are:
- SharedWorker imported via **server-absolute path** (`new URL('/src/workers/...', import.meta.url)`)
  — Turbopack needs a **relative** path (`'../../workers/...'`). Works in webpack too.
- **CSS Modules `:global` nested inside native CSS nesting** in `*.module.css` — Turbopack's
  Lightning CSS parser rejects it (`css-loader` tolerates it). Fix: don't nest `:global {}`;
  reference global keyframes by plain name (they resolve if defined outside the module).
- **`@civitai/client` `ERR_UNSUPPORTED_DIR_IMPORT`** — needs `transpilePackages: ['@civitai/client']`.
  But that also makes the cold compile *slower* (Turbopack then transpiles the large generated client).
- Net: cold compile was not faster; warm was. Parked in favor of the v11 path.

### 5. Hot-path first-request latency
A lazily-loaded module pays a one-time chunk compile on the **first request** to its endpoint
after a server (re)start. Harmless in dev (one-time blip). If lazy routers are ever weighed for
**prod cold-start**, `image.service` (the feed hot path, ~7.9K lines) is the one to watch.

## tRPC v11 upgrade specifics

- Current versions (all need bumping together): `@trpc/server`, `@trpc/client`, `@trpc/next`,
  `@trpc/react-query` — all `^10.45.0`.
- The dev-speed payoff is **`router.lazy()`** — wire it in `src/server/routers/index.ts`,
  ideally heaviest routers first (image, model, post, generation, orchestrator).
- Follow the official v10→v11 migration guide for breaking changes (transformer config moved to
  the link, etc.) — the `superjson` transformer setup in `src/server/trpc.ts` and the client
  links will need updating.
- **Recommended sequence:** (1) enable circular-dependency plugin & fix all reported cycles;
  (2) do the v11 API migration with routers still eager and confirm green typecheck + app boot;
  (3) only then convert routers to `lazy()` incrementally, watching for the runtime `undefined`
  signature from §1 as each is converted.

## Quick reference — files touched in the (reverted) prototype
Server importers of `generation.service` that were converted: `generation.router.ts`,
`model.controller.ts`, `model-version.controller.ts`, `recommenders.controller.ts`,
`model.service.ts`, `post.service.ts`, `orchestrator/common.ts`, `orchestration-new.service.ts`,
`orchestrator/queue-limits.ts`, `models.search-index.ts`. Type-only client imports and
`pages/api/**` importers were left static (separate bundles; don't affect the tRPC route).
Watch for **relative-path** importers (`../services/...`) — a `~/server/...` grep misses them.