trpc-nuxt-module

tRPC for Nuxt. A Nuxt module that registers your router's HTTP handler — and, when you ask for it, a WebSocket handler over Nitro's own WebSockets — fetches through the request event during server rendering so a call never leaves the process, and decorates the typed client with useQuery, useLazyQuery, useMutation and useSubscription, each a composable over Nuxt's own useAsyncData.

Table of Contents

• 🚀 Getting Started
• 📖 Documentation
• ⚖️ License

🚀 Getting Started

pnpm i trpc-nuxt-module @trpc/server @trpc/client

Register the module with the file and export name of your router and your context factory:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["trpc-nuxt-module"],
  trpc: {
    createContext: { from: "~~/server/trpc/context", name: "createContext" },
    endpoint: "/api/trpc",
    router: { from: "~~/server/trpc/router", name: "appRouter" },
    // Optional: tRPC's WebSocket handler at this route, for subscriptions over `wsLink`
    webSocket: { endpoint: "/api/trpc/ws" },
  },
});

// server/trpc/router.ts
import { initTRPC } from "@trpc/server";
import { z } from "zod";

const t = initTRPC.create();

export const appRouter = t.router({ greeting: t.procedure.input(z.string()).query(({ input }) => `Hello ${input}`) });

export type AppRouter = typeof appRouter;

Provide a client from a plugin — createTRPCNuxtClient and the links are auto-imported:

// app/plugins/trpc.ts
import type { AppRouter } from "~~/server/trpc/router";

export default defineNuxtPlugin(() => {
  const trpc = createTRPCNuxtClient<AppRouter>({ links: [httpBatchLink<AppRouter>({ url: "/api/trpc" })] });
  return { provide: { trpc } };
});

And call a procedure from a page:

<script setup lang="ts">
const { $trpc } = useNuxtApp();
const name = ref("world");
const { data } = await $trpc.greeting.useQuery(name);
</script>

<template>
  <p>{{ data }}</p>
</template>

📖 Documentation

We highly recommend you take a look at the documentation to level up. It covers the design and the upstream trpc-nuxt issues this module answers.

Key exports

| Export | Description | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | trpc-nuxt-module | The module — router, createContext, endpoint and webSocket options | | createTRPCNuxtClient | The typed client, every procedure decorated with useQuery, useLazyQuery, useMutation or useSubscription | | httpLink, httpBatchLink | tRPC's links, sending through the request event during server rendering | | getQueryKey, getMutationKey | The useAsyncData keys a procedure's data is cached under, for useNuxtData and refreshNuxtData | | trpc-nuxt-module/runtime/server/createTRPCEventHandler | The HTTP handler over tRPC's fetch adapter, for a Nitro app without Nuxt |

A WebSocket connection's open and close call the trpc-nuxt-module:webSocket:open and trpc-nuxt-module:webSocket:close Nitro runtime hooks with its context, typed off your router.

Commands

Run from packages/trpc-nuxt-module/:

pnpm build        # compile to dist/
pnpm test         # vitest watch mode (coverage is run from the repo root)
pnpm bench        # the event handler against tRPC's own fetch adapter
pnpm lint:fix     # auto-fix lint
pnpm typecheck    # type check

⚖️ License

This project is licensed under the Apache-2.0 license.