trpc-nuxt-module

packages/trpc-nuxt-module (npm trpc-nuxt-module) joins tRPC to Nuxt. Registered in nuxt.config with the file that exports the router and the file that exports the context factory, it generates the HTTP handler at the configured endpoint and, when asked, the WebSocket handler Nitro serves; auto-imports createTRPCNuxtClient, the two HTTP links and the two key helpers; and decorates every procedure on the client with useQuery, useLazyQuery, useMutation and useSubscription, each a composable over Nuxt's own useAsyncData. Nothing about tRPC's protocol is written in the package: the handlers are tRPC's fetch and WebSocket adapters, and the links are tRPC's own with a fetch chosen for where they run.

It replaced trpc-nuxt, which made every app hand-write its tRPC route, its socket bridge, a client plugin and a transpile entry, and is the second worked example of the absorption flow in dependency admission, after trpc-msw.

How a call travels

flowchart TD
  page["page or component<br/>$trpc.x.useQuery()"]
  asyncData["useAsyncData<br/>key follows the input"]
  links["the app's link chain<br/>logger, offline, error"]
  where{"Where is it running?"}
  eventFetch["httpLink / httpBatchLink<br/>fetch = event.fetch"]
  globalFetch["httpLink / httpBatchLink<br/>global fetch, absolute url"]
  wsLink["wsLink"]
  kind{"Subscription?"}
  handler["createTRPCEventHandler<br/>Request from the cached raw body"]
  bridge["createTRPCWebSocketHandler<br/>each peer presented as a ws client"]
  hooks["Nitro runtime hooks<br/>webSocket:open / webSocket:close"]
  router["the app's router<br/>tRPC's own adapters"]
  page --> asyncData --> links --> where
  where -->|"server render"| eventFetch
  where -->|browser| kind
  kind -->|no| globalFetch
  kind -->|yes| wsLink
  eventFetch -->|"in-process, headers forwarded"| handler
  globalFetch -->|network| handler
  wsLink -->|"crossws peer"| bridge
  bridge --> hooks
  handler --> router
  bridge --> router

• Server rendering sends through the request event. event.fetch is Nitro's fetchWithEvent over its in-process fetch: the incoming request's headers are forwarded, no socket is opened, and the answer is a real Response with its headers intact. The link reads the event when it is built, inside the app's context, because a batch sends a tick later when that context is gone.
• The browser sends through the global fetch against an absolute url, which is also what a network interceptor sees, so a test answers the real links, batching included, at the network (trpc-msw).
• The HTTP handler rebuilds the request from what h3 caches: the raw body rather than the stream, so a middleware that read the body first leaves it to be read again; the path Nitro routed on, below any app.baseURL; and a signal aborted when the response closes early, which is what ends a streamed subscription when the client leaves.
• The WebSocket handler is tRPC's applyWSSHandler over crossws. tRPC drives a ws server, so the handler presents one and a ws client per peer — the shape trpc-msw presents an msw connection in — and replays each crossws hook onto the client it belongs to. As a connection opens and closes it calls the trpc-nuxt-module:webSocket:open and :close Nitro runtime hooks with the connection's context, which the app's server/plugins/webSocketConnection.ts answers with the user's connect and disconnect, and on Nitro's close it broadcasts tRPC's reconnect notice so clients resubscribe rather than fail.
• A query's key follows its input. The useAsyncData key is a getter over the procedure path and a hash of the input, so a changed input is fetched and cached under its own key; a fixed queryKey watches the input instead.

Registering it

The module is registered by its options — the router and context as the file and export name each lives under, resolved through Nuxt's aliases, the HTTP endpoint, and optionally the WebSocket endpoint with tRPC's keep-alive. The generated handlers import both from there, and the type template reads the router's context type for the hooks. A value the module owns itself — the hook names — is imported by the generated handler from the module's runtime rather than written into it, so the only literals spliced into generated code are the app's own options; CodeQL's js/bad-code-sanitization fails main on a splice of the module's constants. Inside this repository it is registered by the path to its source module rather than its package name: nuxt prepare loads every module from the app's postinstall, before any workspace package is built, and a package name resolves to a dist a fresh clone does not have yet. That rule, and the package shape it belongs to, is Nuxt module packages.

The app keeps only what is its own: app/plugins/trpc.ts composes its logger, offline and error links around the module's transport links and provides the client createTRPCNuxtClient returns.

Upstream

All of trpc-nuxt's tracker is below, grouped where several items share one answer, and graded by the triage that page defines; each defect is proven by the named test in packages/trpc-nuxt-module/src — the event handler, WebSocket handler, client and link suites, or the type tests beside the models.

Never ported: ofetch options on the links (its fetch options and header picking), which configured a transport the links no longer use — tRPC's own fetch and headers options are the seam, and event.fetch forwards the request's headers itself; a default link url, since the endpoint is the module's option and a default the links did not share with it would disagree the day it changed; and the upstream abort-on-unmount flag, since useAsyncData aborts a superseded or unmounted fetch through the signal it hands the handler.

Notes

• The handler costs more than tRPC's bare fetch adapter, and more than the upstream handler in-process: reading the cached raw body and arming the abort signal are what fix the middleware-read body and the leaked subscription, and each is microseconds against a procedure's own work. The committed createTRPCEventHandler.bench.md beside the handler is the number.
• Instantiation budgets for the client's types are not asserted yet. @ark/attest passed the admission gate but cannot count instantiations through this repository's tsgo-backed typescript; the type tests carry the @TODO that says what waits.

Key files

Sources

• wobsoriano/trpc-nuxt — the package replaced, its issues and pull requests.
• Module author guide, module anatomy, recipes and best practices (Nuxt) — defineNuxtModule, the runtime directory, server and type templates, prefixed runtime hooks.
• useAsyncData (Nuxt) — the reactive key, enabled, and the abort signal the handler receives.
• useRequestEvent (Nuxt) — the event whose fetch is the server-rendering transport.
• WebSocket (Nitro) — defineWebSocketHandler and the experimental.websocket flag the module sets.
• Fetch adapter and WebSockets (tRPC) — the two handlers the module wraps.
• nuxt-security XSS validator — the filter whose semantics keep it off.