trpc-patterns

TRPC with Tanstack Query patterns Applies to files matching: *.tsx.

⭐844stars🔀89forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

This Claude skill provides standardized patterns for integrating tRPC with Tanstack Query in TypeScript and React environments. It streamlines full-stack development by offering pre-defined structures for backend routers, frontend hooks, and Drizzle ORM database operations, ensuring end-to-end type safety and robust state management.

Use Cases

  • Full-stack Feature Scaffolding: Quickly create type-safe API endpoints and corresponding React hooks for new application features.
  • Efficient Data Fetching: Implement optimized query patterns and cache invalidation strategies using Tanstack Query to improve application performance.
  • Secure API Development: Enforce consistent input validation with Zod and secure backend procedures using standardized authentication patterns.
  • Database Integration: Streamline database interactions by separating query logic from API routes using Drizzle ORM best practices.
nametrpc-patterns
descriptionTRPC with Tanstack Query patterns Applies to files matching: *.tsx.

TRPC with Tanstack Query Integration

Backend Structure

  • Main router: trpc/routers/_app.ts - All routers must be registered here
  • Individual routers: trpc/routers/*.router.ts - Create feature-specific routers (e.g., chat.router.ts, vote.router.ts)
  • Database queries: lib/db/queries.ts - All database operations should be defined here
  • Database schema: lib/db/schema.ts - Drizzle ORM schema definitions

Frontend Integration

Setup

  • Use useTRPC() hook from @/trpc/react
  • Import useMutation, useQuery, useQueryClient from @tanstack/react-query

Query Pattern

const trpc = useTRPC();
const { data, isLoading, refetch } = useQuery({
  ...trpc.router.procedure.queryOptions(),
  enabled: !!condition,
});

Mutation Pattern

const trpc = useTRPC();
const queryClient = useQueryClient();

const mutation = useMutation(
  trpc.router.procedure.mutationOptions({
    onSuccess: () => {
      // Invalidate related queries
      queryClient.invalidateQueries({
        queryKey: trpc.router.relatedQuery.queryKey(),
      });
    },
  })
);

// Usage
await mutation.mutateAsync({ input: data });

Backend Router Pattern

import { createTRPCRouter, protectedProcedure } from '@/trpc/init';
import { z } from 'zod';

export const featureRouter = createTRPCRouter({
  queryName: protectedProcedure.query(async ({ ctx }) => {
    return await dbFunction({ userId: ctx.user.id });
  }),

  mutationName: protectedProcedure
    .input(z.object({ /* validation schema */ }))
    .mutation(async ({ ctx, input }) => {
      // Verify permissions/ownership
      // Call database function
      return await dbFunction(input);
    }),
});

Key Principles

  1. Always use protectedProcedure for authenticated routes
  2. Validate inputs with Zod schemas
  3. Verify user ownership/permissions in mutations
  4. Use database functions from lib/db/queries.ts
  5. Invalidate related queries after mutations
  6. Handle loading and error states in the UI