tRPC-SvelteKit

To integrate tRPC-SvelteKit into your SvelteKit application, follow these steps to set up the router, context, and server handle.

1. Install dependencies:

   yarn add trpc-sveltekit @trpc/server @trpc/client

2. Create a tRPC router (e.g., in lib/trpc/router.ts): Initialize tRPC using your context type and define your procedures.

3. Create a tRPC context (e.g., in lib/trpc/context.ts): Define an async function that returns the context object used by your procedures.

4. Add the tRPC handle to SvelteKit hooks (in hooks.server.ts): Use createTRPCHandle to bridge SvelteKit requests to your tRPC router.

To enable the experimental WebSocket server, you must modify your build configuration files.

In vite.config.ts:

import { sveltekit } from '@sveltejs/kit/vite';
import type { UserConfig } from 'vite';
import { vitePluginTrpcWebSocket } from 'trpc-sveltekit/websocket';

const config: UserConfig = {
  plugins: [
    sveltekit(),
    vitePluginTrpcWebSocket
  ]
};

export default config;

In svelte.config.js:

import adapter from '@sveltejs/adapter-node';
// ...

Create wsServer.js (next to package.json):

import { SvelteKitTRPCWSServer } from "trpc-sveltekit/websocket";

SvelteKitTRPCWSServer(import.meta.url);

Update package.json scripts:

{
  "scripts": {
    "start": "node ./wsServer"
  }
}

When using WebSocket support, use createTRPCWebSocketClient to create the proxy client. Unlike the standard HTTP client, this client does not require the $page store passed to its method calls.

// lib/trpc/client.ts
import type { Router } from '$lib/trpc/router';
import { createTRPCWebSocketClient } from "trpc-sveltekit/websocket";

let browserClient: ReturnType<typeof createTRPCWebSocketClient<Router>>;

export function trpc() {
  const isBrowser = typeof window !== 'undefined';
  if (isBrowser && browserClient) return browserClient;
  const client = createTRPCWebSocketClient<Router>();
  if (isBrowser) browserClient = client;
  return client;
}

// Usage in +page.svelte
// const greeting = await trpc().greeting.query();

Define your API surface by creating a router using initTRPC. You must pass your context type to initTRPC.context<Context>() to ensure end-to-end type safety.

// lib/trpc/router.ts
import type { Context } from '$lib/trpc/context';
import { initTRPC } from '@trpc/server';
import delay from 'delay';

export const t = initTRPC.context<Context>().create();

export const router = t.router({
  greeting: t.procedure.query(async () => {
    await delay(500); // simulate an expensive operation
    return `Hello tRPC v10 @ ${new Date().toLocaleTimeString()}`;
  })
});

export type Router = typeof router;

To enable tRPC endpoints in your SvelteKit app, you must register the tRPC handler in your hooks.server.ts file using createTRPCHandle.

// hooks.server.ts
import { createContext } from '$lib/trpc/context';
import { router } from '$lib/trpc/router';
import type { Handle } from '@sveltejs/kit';
import { createTRPCHandle } from 'trpc-sveltekit';

export const handle: Handle = createTRPCHandle({ router, createContext });

In hooks.server.ts, you must initialize the WebSocket server. It is critical to wrap this in a !building check to avoid failures during the SvelteKit build/prerender process.

// hooks.server.ts
import { createContext } from '$lib/trpc/context';
import { router } from '$lib/trpc/router';
import { createTRPCWebSocketServer } from "trpc-sveltekit/websocket";
import { building } from '$app/environment';

if (!building) createTRPCWebSocketServer({ router, createContext })

To enable experimental WebSocket support during development, add vitePluginTrpcWebSocket to your vite.config.ts plugins array. This plugin initializes a global WebSocket server instance and attaches an upgrade handler to the Vite development server's HTTP server, allowing tRPC WebSocket connections to be handled during local development.

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import { vitePluginTrpcWebSocket } from 'trpc-sveltekit/websocket'; // Note: exact import path depends on package exports

export default defineConfig({
  plugins: [
    sveltekit(),
    vitePluginTrpcWebSocket
  ]
});

The onError option allows you to intercept and handle tRPC errors globally. The callback receives an object with these properties:

• ctx: The tRPC context.
• error: The TRPCError instance.
• path: The procedure path.
• input: The input provided to the procedure.
• req: The RequestInit object.
• type: The ProcedureType or 'unknown'.

The trpc-sveltekit package exports all functionality from its client and server modules. You can import the necessary tools for both the tRPC server-side setup (routers, context, handlers) and the client-side usage (tRPC client) directly from the package entrypoint.

import { ... } from 'trpc-sveltekit';