tRPC guide SvelteKit: The Definitive Guide to performance for Developers

// src/lib/server/trpc.ts
// tRPC server initialization with SvelteKit-specific context, error formatting, and performance middleware
import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod'; // v3.23.0 for input validation
import type { RequestEvent } from '@sveltejs/kit'; // SvelteKit 2.5.0 types

// Define context type: includes SvelteKit request event, user session, and performance timers
interface TRPCContext {
  event: RequestEvent;
  user?: { id: string; role: 'admin' | 'user' };
  startTime: number;
}

// Initialize tRPC with context and error formatting
const t = initTRPC.context().create({
  // Custom error formatter: strips internal stack traces in prod, logs metrics
  errorFormatter({ shape, error }) {
    const isProd = process.env.NODE_ENV === 'production';
    return {
      ...shape,
      data: {
        ...shape.data,
        // Only expose stack traces in non-production environments
        stack: isProd ? undefined : error.stack,
        // Custom metric tags for observability
        metricTags: {
          procedure: shape.data.procedure,
          errorCode: shape.code,
          latencyMs: Date.now() - (error as any).context?.startTime || 0
        }
      }
    };
  },
  // Global middleware: adds performance timing, request logging, and rate limiting
  middleware: (opts) => {
    const startTime = Date.now();
    // Attach start time to context for latency calculation
    opts.ctx.startTime = startTime;

    // Basic rate limiting: 100 requests per minute per IP
    const ip = opts.ctx.event.request.headers.get('x-forwarded-for') || 'unknown';
    const rateLimitKey = `trpc:ratelimit:${ip}`;
    // Note: In production, use Upstash Redis or Cloudflare KV for rate limiting
    // This is a simplified in-memory example for demo purposes
    const now = Date.now();
    const windowMs = 60 * 1000; // 1 minute
    const stored = globalThis.__rateLimitStore?.get(rateLimitKey);
    if (stored && stored.count >= 100 && now - stored.start < windowMs) {
      throw new TRPCError({
        code: 'TOO_MANY_REQUESTS',
        message: 'Rate limit exceeded: 100 requests per minute'
      });
    }
    globalThis.__rateLimitStore?.set(rateLimitKey, {
      count: (stored?.count || 0) + 1,
      start: stored?.start || now
    });

    // Execute procedure
    const result = opts.next({
      ctx: {
        ...opts.ctx,
        startTime
      }
    });

    // Log latency for slow procedures (>100ms)
    result.then(() => {
      const latency = Date.now() - startTime;
      if (latency > 100) {
        console.warn(`Slow tRPC procedure: ${opts.path} took ${latency}ms`);
      }
    });

    return result;
  }
});

// Export tRPC helpers
export const router = t.router;
export const publicProcedure = t.procedure;
export const protectedProcedure = t.procedure.use(async (opts) => {
  // Check for user session in SvelteKit event
  const session = await opts.ctx.event.locals.getSession();
  if (!session?.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return opts.next({
    ctx: {
      ...opts.ctx,
      user: session.user
    }
  });
});
export const createContext = async (event: RequestEvent): Promise => {
  return {
    event,
    startTime: Date.now()
  };
};

// src/hooks.server.ts
// SvelteKit server hooks to initialize tRPC context and handle tRPC requests
import { createTRPCRouter } from './lib/server/trpc';
import { appRouter } from './lib/server/router'; // Our tRPC router (defined next)
import type { RequestEvent } from '@sveltejs/kit';
import { fetchRequestHandler } from '@trpc/server/adapters/fetch'; // v11 adapter for SvelteKit

// Initialize tRPC request handler with SvelteKit adapter
const trpcHandler = fetchRequestHandler({
  endpoint: '/api/trpc', // tRPC endpoint path
  router: appRouter,
  createContext: ({ req }) => {
    // SvelteKit passes the event as part of the request? Wait no, need to get the event from the hook.
    // SvelteKit server hooks receive the event, so we need to pass it to createContext.
    // Adjusting: the fetchRequestHandler's createContext gets the request, but we need the SvelteKit event.
    // So we wrap the handler to inject the event.
  },
  onError({ error, path }) {
    // Log tRPC errors to SvelteKit's logger
    console.error(`tRPC error on ${path}:`, error);
  }
});

// Server hook: handle all requests, pass tRPC requests to handler, others to next
export async function handle({ event, resolve }: { event: RequestEvent; resolve: any }) {
  // Check if request is for tRPC endpoint
  if (event.url.pathname.startsWith('/api/trpc')) {
    // Create tRPC context with SvelteKit event
    const context = await createTRPCRouter.createContext(event);
    // Pass context to fetchRequestHandler
    return trpcHandler(event.request, { context });
  }
  // For non-tRPC requests, resolve normally
  return resolve(event);
}

// Optional: SvelteKit session handling for protected procedures
export async function getSession(event: RequestEvent) {
  // In production, use SvelteKit's session store or Auth.js
  // This is a simplified example using a cookie
  const sessionCookie = event.cookies.get('session');
  if (!sessionCookie) return null;
  try {
    const session = JSON.parse(atob(sessionCookie));
    return session;
  } catch {
    return null;
  }
}

// src/lib/client/trpc.ts
// tRPC client configuration for SvelteKit with batching, caching, and error handling
import { createTRPCProxyClient, httpBatchLink, loggerLink, wsLink } from '@trpc/client';
import type { AppRouter } from '../server/router'; // Type-safe router import
import { readable, writable } from 'svelte/store'; // Svelte 4 stores
import { browser } from '$app/environment'; // SvelteKit environment check

// Configuration for tRPC client: batching, links, caching
const trpcClient = createTRPCProxyClient({
  links: [
    // Logger link: logs requests in development
    loggerLink({
      enabled: () => process.env.NODE_ENV === 'development',
      // Custom logger: logs procedure name, input, and latency
      logger: (opts) => {
        const { path, input, ctx } = opts;
        const latency = Date.now() - (ctx as any).startTime;
        console.log(`tRPC Client: ${path}`, { input, latency: `${latency}ms` });
      }
    }),
    // Batch link: batches multiple procedure calls into a single request
    httpBatchLink({
      url: '/api/trpc', // Matches server endpoint
      // Optional: disable batching for specific procedures
      batch: (calls) => {
        // Don't batch mutations to avoid partial failures
        const hasMutation = calls.some((call) => call.path.includes('mut'));
        return !hasMutation;
      },
      // Headers: pass session cookie for protected procedures
      headers: () => {
        const headers = new Headers();
        if (browser) {
          const session = localStorage.getItem('session');
          if (session) headers.set('Authorization', `Bearer ${session}`);
        }
        return headers;
      },
      // Fetch implementation: use SvelteKit's fetch for SSR compatibility
      fetch: (url, options) => {
        // In SvelteKit, use the event's fetch for server-side requests
        // This is handled via the client's fetch override in SvelteKit components
        return fetch(url, { ...options, credentials: 'include' });
      }
    }),
    // WebSocket link: optional for real-time subscriptions (if using tRPC subscriptions)
    ...(browser
      ? [
          wsLink({
            url: 'ws://localhost:3000/api/trpc',
            // Reconnect on disconnect
            reconnect: true,
            // Connection params: pass session token
            connectionParams: () => {
              const session = localStorage.getItem('session');
              return { token: session };
            }
          })
        ]
      : [])
  ]
});

// Svelte store for tRPC client state: loading, error, data
export const trpcStore = writable<{
  client: typeof trpcClient;
  isLoading: boolean;
  error: Error | null;
}>({
  client: trpcClient,
  isLoading: false,
  error: null
});

// Helper function to call tRPC procedures with error handling and loading state
export async function callTRPC(
  procedure: (client: typeof trpcClient) => Promise,
  onSuccess?: (data: T) => void,
  onError?: (error: Error) => void
) {
  trpcStore.update((state) => ({ ...state, isLoading: true, error: null }));
  try {
    const client = trpcClient;
    const data = await procedure(client);
    onSuccess?.(data);
    return data;
  } catch (error) {
    const trpcError = error as any;
    const message = trpcError.message || 'Unknown tRPC error';
    trpcStore.update((state) => ({ ...state, error: new Error(message) }));
    onError?.(new Error(message));
    throw error;
  } finally {
    trpcStore.update((state) => ({ ...state, isLoading: false }));
  }
}

// src/routes/api/trpc/+server.ts (SvelteKit edge route for tRPC)
export const config = {
  runtime: 'edge' // Enable Cloudflare/Vercel Edge runtime
};

import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { appRouter } from '$lib/server/router';

export const GET = (event) => {
  return fetchRequestHandler({
    endpoint: '/api/trpc',
    router: appRouter,
    createContext: () => ({ event }),
    req: event.request
  });
};
export const POST = GET;

// Custom batch function for httpBatchLink
httpBatchLink({
  url: '/api/trpc',
  batch: (calls) => {
    // Split mutations and queries into separate batches
    const mutations = calls.filter((c) => c.path.startsWith('mutation'));
    const queries = calls.filter((c) => c.path.startsWith('query'));
    const analytics = calls.filter((c) => c.path.includes('analytics'));

    // Don't batch mutations at all
    const batches = [];
    if (mutations.length) batches.push(...mutations.map((c) => [c]));
    // Batch queries up to 10 per batch
    while (queries.length) batches.push(queries.splice(0, 10));
    // Batch analytics separately
    if (analytics.length) batches.push(analytics);

    return batches;
  }
})

// tRPC middleware for response caching
const cacheMiddleware = t.middleware(async (opts) => {
  // Only cache public procedures (no user context)
  if (opts.ctx.user) return opts.next();

  const cacheKey = `trpc:cache:${opts.path}:${JSON.stringify(opts.input)}`;
  // Check cache first (use Cloudflare KV or SvelteKit's cache in production)
  const cached = await caches.default?.match(cacheKey);
  if (cached) return cached.json();

  const result = await opts.next();

  // Cache successful responses for 60 seconds
  if (result.ok) {
    const response = new Response(JSON.stringify(result.data), {
      headers: { 'Content-Type': 'application/json', 'Cache-Control': 'public, max-age=60, stale-while-revalidate=30' }
    });
    await caches.default?.put(cacheKey, response);
  }

  return result;
});

// Apply to public read procedures
export const cachedProcedure = publicProcedure.use(cacheMiddleware);

// benchmark.js
import http from 'k6/http';
import { check, sleep } from 'k6';
import { Rate } from 'k6/metrics';

const errorRate = new Rate('errors');

export const options = {
  stages: [
    { duration: '30s', target: 100 }, // Ramp up to 100 users
    { duration: '5m', target: 100 }, // Stay at 100 users for 5 minutes
    { duration: '30s', target: 0 }, // Ramp down
  ],
  thresholds: {
    'http_req_duration{p99:>500}': ['p(99)<500'], // p99 latency <500ms
    errors: ['rate<0.1'], // Error rate <10%
  },
};

const baseUrl = 'http://localhost:3000';
const trpcEndpoint = `${baseUrl}/api/trpc`;

// tRPC batch request payload for 5 CRUD procedures
const batchPayload = {
  '0': { path: 'user.list', input: {} },
  '1': { path: 'user.get', input: { id: '1' } },
  '2': { path: 'post.create', input: { title: 'Test Post', content: 'Benchmark' } },
  '3': { path: 'post.update', input: { id: '1', title: 'Updated' } },
  '4': { path: 'post.delete', input: { id: '1' } },
};

export default function () {
  // Send batched tRPC request
  const res = http.post(trpcEndpoint, JSON.stringify(batchPayload), {
    headers: { 'Content-Type': 'application/json' },
  });

  // Check response
  const success = check(res, {
    'status is 200': (r) => r.status === 200,
    'no errors': (r) => !r.json().errors,
  });

  errorRate.add(!success);

  sleep(1);
}

trpc-sveltekit-perf-guide/
├── src/
│   ├── lib/
│   │   ├── server/
│   │   │   ├── trpc.ts       # tRPC server init (code example 1)
│   │   │   ├── router.ts     # App router with procedures
│   │   │   └── middlewares/  # Cache, rate limit middlewares
│   │   ├── client/
│   │   │   └── trpc.ts       # tRPC client init (code example 3)
│   │   └── types/
│   ├── routes/
│   │   ├── api/trpc/
│   │   │   └── +server.ts    # Edge runtime tRPC handler
│   │   └── dashboard/
│   │       ├── +page.svelte  # Dashboard with tRPC calls
│   │       └── +page.ts      # SSR load function with tRPC
│   ├── hooks.server.ts       # SvelteKit server hooks (code example 2)
│   └── hooks.client.ts
├── static/
├── package.json
├── svelte.config.js
├── tsconfig.json
└── vite.config.ts