tRPC API

This guide explains how to use the tRPC integration for type-safe API calls in the application, including available routes, custom hooks, and best practices.

This template uses tRPC with react-query under the hood. For more information, go to tRPC docs

Overview

tRPC enables end-to-end typesafe APIs, ensuring that your frontend and backend are always in sync without schema validation or code generation. Our application implements a structured tRPC router system with dedicated hooks for common operations.

Key Benefits

1
Full type safety between client and server
2
Automatic API documentation through TypeScript
3
Simplified error handling
4
Integrated with React Query for caching and state management
5
Zero configuration for most use cases

Available Routes

The application organizes tRPC routes into logical groups by feature. Below are the available routers defined in _app.ts:

trpc.users.*

User management operations

trpc.items.*

CRUD operations for items

trpc.notifications.*

User notification management

trpc.workspaces.*

Workspace operations

trpc.members.*

Workspace member management

trpc.invitations.*

Invitation creation and handling

trpc.usersSettings.*

User settings management

trpc.subscriptions.*

Subscription management

trpc.feedbacks.*

User feedback submission

Router Configuration

trpc/routers/_app.ts

TYPESCRIPT

Custom Hooks

Each router has dedicated hooks organized in files like items-hooks.ts or users-hooks.ts. These hooks encapsulate common functionality and provide built-in error handling, toast notifications, and cache invalidation.

Item Hooks Example

Custom hooks for item operations defined in items-hooks.ts:

trpc/hooks/items-hooks.ts

TYPESCRIPT

Using tRPC Hooks

Using Mutation Hooks

Example of using a tRPC mutation hook in a component:

TYPESCRIPT

Using Query Hooks

Example of fetching data with tRPC queries:

TYPESCRIPT

Type Safety Benefits

Automatic Type Inference

Types flow from your backend to frontend without any manual work.

TYPESCRIPT

Input Validation

Input validation happens at compile time and runtime.

TYPESCRIPT

Error Handling

Errors are properly typed and can be handled gracefully.

TYPESCRIPT

Hook Patterns

Common Hook Structure

1
Import dependencies - Import tRPC client and other utilities
2
Access tRPC utilities - Get access to the tRPC client
3
Setup mutation or query - Configure the tRPC operation
4
Handle success/error cases - Manage toast messages and state updates
5
Return necessary values - Expose mutate function, loading state, etc.

Cache Invalidation

TYPESCRIPT

Best Practices

Hook Organization

1
Group related hooks in feature-specific files
2
Keep hooks focused on single responsibilities
3
Provide optional callback props for flexibility
4
Handle errors consistently across hooks

Type Safety

1
Leverage TypeScript's inference capabilities
2
Define input and output types explicitly for complex operations
3
Avoid using 'any' or type assertions
4
Use zod schemas for validation

Performance

1
Use proper cache invalidation strategies
2
Implement optimistic updates for better UX
3
Use suspense mode when appropriate
4
Enable prefetching for frequently accessed data

Error Handling

1
Provide descriptive error messages
2
Use toast notifications for user feedback
3
Handle different error types appropriately
4
Implement proper fallbacks and loading states

Key Features

🔄

End-to-End Type Safety

Full TypeScript integration from backend to frontend

⚡

React Query Integration

Built-in caching, refetching, and state management

🛡️

Error Handling

Standardized error handling with custom error types

🔍

Developer Experience

Autocomplete and type checking in your IDE

Client Configuration

tRPC Client Setup

TYPESCRIPT

When adding new tRPC routes, make sure to follow the established patterns and create corresponding hook files to maintain consistency across the application. Learn more about tRPC