Cline

# Security Best Practices Standards for tRPC This document outlines security best practices for tRPC applications. Adhering to these standards helps protect against common vulnerabilities, ensures data integrity, and promotes the development of secure and reliable applications. ## 1. Input Validation and Sanitization ### Standards * **Do This:** Always validate and sanitize all inputs received from the client. Define input schemas with Zod or similar validation libraries that support the specific data types and constraints you expect. * **Do This:** Use "z.preprocess" or similar Zod functionalities to sanitize and transform data before validation to normalize inputs, prevent injection attacks, and avoid errors due to unexpected characters. * **Don't Do This:** Rely on client-side validation alone. Client-side validation can be bypassed, making server-side validation crucial. * **Don't Do This:** Pass raw user input directly to database queries or system commands without validation or sanitization. ### Explanation Input validation is essential to prevent various attacks, including SQL injection, cross-site scripting (XSS), and command injection. Validating and sanitizing data ensures it conforms to expected formats and does not contain malicious code. tRPC simplifies this process by integrating seamlessly with Zod for schema definition and validation. ### Code Example """typescript import { z } from 'zod'; import { publicProcedure, router } from './trpc'; const userInputSchema = z.object({ email: z.string().email(), username: z.string().min(3).max(20).regex(/^[a-zA-Z0-9]+$/), // Only alphanumeric characters allowed profileDescription: z.string().max(200).optional().transform(val => val?.trim()), // Trim whitespace }); export const appRouter = router({ createUser: publicProcedure .input(userInputSchema) .mutation(async ({ input }) => { // Input is guaranteed to be valid based on the schema const { email, username, profileDescription } = input; // Database interaction (example) // Using an ORM like Prisma is recommended to further prevent SQL injection const user = await prisma.user.create({ data: { email, username, profileDescription, }, }); return user; }), }); export type AppRouter = typeof appRouter; """ ### Anti-Patterns * Failing to validate input length, format, or type constraints. * Using basic string replacements as the sole sanitization method. Regular expressions and dedicated sanitization libraries offer more robust protection. * Omitting validation for optional fields, which can still introduce vulnerabilities if present with malicious data. ## 2. Authentication and Authorization ### Standards * **Do This:** Implement authentication to verify the identity of users accessing the application. Use secure authentication methods such as OAuth 2.0 or JWT. * **Do This:** Utilize authorization to manage user permissions and restrict access to sensitive data and procedures. Employ role-based access control (RBAC) or attribute-based access control (ABAC) as needed. * **Do This:** Protect API keys and secrets. Never expose them in client-side code. Store API keys in environment variables and access them securely on the server. * **Don't Do This:** Rely solely on cookies for authentication. Cookies can be vulnerable to cross-site scripting (XSS) and cross-site request forgery (CSRF) attacks. Use secure, httpOnly cookies with proper SameSite attributes. * **Don't Do This:** Store sensitive user data, such as passwords, in plain text. Always hash passwords using bcrypt or Argon2 and store the hashed values. ### Explanation Authentication confirms *who* the user is, while authorization dictates *what* a user can do. Robust authentication and authorization mechanisms are critical to preventing unauthorized access and maintaining data integrity. tRPC does not handle authentication/authorization directly, so integration with existing solutions is necessary. ### Code Example """typescript import { TRPCError } from '@trpc/server'; import { z } from 'zod'; import { publicProcedure, router, middleware } from './trpc'; import { verifyJwtToken } from './auth-utils'; // Custom JWT verification function // Authentication Middleware const authMiddleware = middleware(async ({ ctx, next }) => { const token = ctx.req.headers.authorization?.split(' ')[1]; // Bearer <token> if (!token) { throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Missing authentication token' }); } try { const user = await verifyJwtToken(token); return next({ ctx: { ...ctx, user, // Add user information to the context }, }); } catch (error) { throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid authentication token' }); } }); // Protected Procedure const protectedProcedure = publicProcedure.use(authMiddleware); export const appRouter = router({ getUserProfile: protectedProcedure .query(async ({ ctx }) => { // Access user information from the context const userId = ctx.user.id; const userProfile = await prisma.user.findUnique({ where: { id: userId } }); if (!userProfile) { throw new TRPCError({ code: 'NOT_FOUND', message: 'User profile not found' }); } return userProfile; }), updateProfile: protectedProcedure .input(z.object({ bio: z.string().max(200) })) .mutation(async ({ input, ctx }) => { const userId = ctx.user.id; const updatedProfile = await prisma.user.update({ where: { id: userId }, data: { bio: input.bio }, }); return updatedProfile; }), }); export type AppRouter = typeof appRouter; """ ### Anti-Patterns * Using weak or predictable credentials. Enforce strong password policies. * Implementing "forgot password" functionality without proper security measures. * Failing to invalidate tokens after a password reset or account compromise. * Granting excessive permissions to users, violating the principle of least privilege. * Not implementing proper CORS (Cross-Origin Resource Sharing) configurations, allowing unauthorized domains to access your tRPC API. ## 3. Cross-Site Scripting (XSS) Prevention ### Standards * **Do This:** Sanitize all output rendered in the browser to prevent XSS attacks. Use templating engines or libraries that automatically escape HTML entities or implement a Content Security Policy (CSP). * **Do This:** Use "DOMPurify" or similar libraries for more complex HTML sanitization, especially when allowing users to input HTML content. * **Don't Do This:** Directly render user-supplied data in HTML without proper escaping or sanitization. ### Explanation XSS attacks occur when malicious scripts are injected into web pages viewed by other users. Sanitizing output and using CSP can prevent these attacks by ensuring that only trusted code is executed in the browser. While tRPC handles communication, XSS is more commonly a frontend concern when rendering the data received from tRPC. ### Code Example While XSS prevention is primarily a frontend concern, it's still relevant when considering data flowing from tRPC. The focus is on how data is handled *after* it's received from the tRPC server. """typescript // Example using React and DOMPurify on the Frontend AFTER data is retrieved from tRPC import React from 'react'; import DOMPurify from 'dompurify'; interface Props { unsafeHTML: string; // Data fetched from a tRPC procedure } function SafeDisplay({ unsafeHTML }: Props) { const cleanHTML = DOMPurify.sanitize(unsafeHTML); return ( <div dangerouslySetInnerHTML={{ __html: cleanHTML }} /> ); } export default SafeDisplay; """ ### Anti-Patterns * Using "dangerouslySetInnerHTML" in React without proper sanitization. * Allowing users to upload arbitrary files that can be interpreted as HTML or JavaScript. * Not configuring a Content Security Policy (CSP) to restrict the sources of content that the browser is allowed to load. ## 4. Cross-Site Request Forgery (CSRF) Prevention ### Standards * **Do This:** Implement CSRF protection to prevent unauthorized actions on behalf of authenticated users. Use synchronizer tokens or the SameSite cookie attribute. * **Do This:** Ensure your tRPC API is only accessible from your intended domain. * **Don't Do This:** Rely solely on cookies for authentication, as they are automatically sent with every request, making your application vulnerable to CSRF attacks if not properly protected. ### Explanation CSRF attacks occur when an attacker tricks a user into performing actions on a web application without their knowledge. CSRF protection mechanisms, such as synchronizer tokens and the SameSite cookie attribute, can prevent these attacks by ensuring that requests originate from the legitimate application. tRPC itself doesn't have built-in CSRF protection, so you rely on your framework/libraries. ### Code Example (Next.js with CSRF Protection) This example showcases CSRF protection using the "csrf-sync" library in a Next.js application, demonstrating a common approach to protecting tRPC endpoints. Note that the "csrf-sync" library generates and validates CSRF tokens, helping to mitigate CSRF attacks. """typescript // pages/api/trpc/[trpc].ts (API Route) import { appRouter } from '../../../server/router'; import { fetchRequestHandler } from '@trpc/server/adapters/fetch'; import { csrf } from 'csrf-sync'; const { generateToken, verifyToken, getTokenFromRequest, loadMiddleware, } = csrf({ size: 32, secret: 'a-very-long-and-complex-string-to-use-as-a-secret', salt: 'xxxx', getTokenFromRequest: (req) => { if (req.headers['x-csrf-token']) { return req.headers['x-csrf-token'] as string; } return ''; }, }); const handler = async (req: NextApiRequest, res: NextApiResponse) => { await loadMiddleware(req, res); const token = generateToken(res); res.setHeader('X-CSRF-Token', token); return fetchRequestHandler({ endpoint: '/api/trpc', req, res, router: appRouter, createContext: () => ({ req, res }), onError({ error, path, input, ctx, req }) { console.error('Error:', error); if (error.code === 'BAD_REQUEST') { } }, }); }; export default handler; // server/router.ts (tRPC Router) import { publicProcedure, router } from '../trpc'; import { z } from 'zod'; export const appRouter = router({ protectedMutation: publicProcedure .input(z.object({ data: z.string() })) .mutation(async ({ input }) => { // Perform the mutation logic here return { success: true, message: "Data processed: ${input.data}" }; }), }); export type AppRouter = typeof appRouter; """ ### Anti-Patterns * Not using a CSRF protection mechanism at all. * Using a weak or predictable CSRF token. * Failing to validate the CSRF token on every state-changing request. * Allowing cross-origin requests without proper CORS configuration. ## 5. Rate Limiting and DoS Protection ### Standards * **Do This:** Implement rate limiting to prevent abuse and protect against denial-of-service (DoS) attacks. Limit the number of requests from a single IP address or user within a specified time frame. * **Do This:** Use middleware to apply rate limiting rules to specific procedures or the entire tRPC API. * **Don't Do This:** Rely solely on client-side rate limiting, as it can be easily bypassed. * **Don't Do This:** Expose sensitive procedures without rate limiting. ### Explanation Rate limiting restricts the number of requests a client can make within a given time period, preventing abuse, protecting against DoS attacks, and ensuring fair usage of resources. ### Code Example """typescript import { TRPCError } from '@trpc/server'; import { publicProcedure, router, middleware } from './trpc'; import { rateLimit } from './rate-limit'; // Custom rate limiting utility // Rate Limiting Middleware const rateLimitMiddleware = middleware(async ({ ctx, next }) => { const identifier = ctx.req.headers['x-forwarded-for'] || ctx.req.socket.remoteAddress; // Get client IP address if (!identifier) { throw new TRPCError({ code: 'INTERNAL_SERVER_ERROR', message: 'Could not determine client IP' }); } const rateLimitResult = await rateLimit(identifier, 10, '60 s'); // Allow 10 requests per IP address every 60 seconds if (!rateLimitResult.success) { throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: 'Rate limit exceeded' }); } return next({ ctx, }); }); // Protected Procedure with Rate Limiting const rateLimitedProcedure = publicProcedure.use(rateLimitMiddleware); export const appRouter = router({ expensiveOperation: rateLimitedProcedure .query(async () => { // Perform an expensive operation here return { success: true }; }), }); export type AppRouter = typeof appRouter; """ """typescript // rate-limit.ts (Example Rate Limiting Implementation - using Redis) import { Redis } from '@upstash/redis' const redis = new Redis({ url: process.env.UPSTASH_REDIS_REST_URL, token: process.env.UPSTASH_REDIS_REST_TOKEN, }) export async function rateLimit(identifier: string, limit: number, timeFrame: string) { const key = "rateLimit:${identifier}"; const { remaining, reset } = await redis.incr(key) .set('ex', timeFrame).then(res => { return { remaining: limit - res, reset: parseInt(timeFrame) } }) const success = remaining >= 0; return { success, reset, remaining }; } """ ### Anti-Patterns * Not implementing rate limiting at all. * Using overly generous rate limits that allow for abuse. * Failing to handle rate limit errors gracefully on the client side. * Relying on a single rate limiting scheme that doesn't adapt to different types of requests. ## 6. Error Handling and Logging ### Standards * **Do This:** Implement robust error handling to catch and handle exceptions gracefully. Return meaningful error messages to the client without exposing sensitive information. * **Do This:** Use structured logging to record application events and errors. Include relevant context in log messages, such as user IDs, request parameters, and timestamps. * **Don't Do This:** Expose stack traces or internal error details to the client. This can reveal sensitive information about your application. * **Don't Do This:** Ignore errors or fail to log them properly. Unhandled errors can lead to unexpected behavior and security vulnerabilities. ### Explanation Proper error handling and logging are crucial for diagnosing issues, monitoring application health, and identifying potential security threats. ### Code Example """typescript import { TRPCError } from '@trpc/server'; import { publicProcedure, router } from './trpc'; import { z } from 'zod'; import logger from './logger'; // Custom logger export const appRouter = router({ getData: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ input }) => { try { const data = await someAsyncOperation(input.id); if (!data) { throw new TRPCError({ code: 'NOT_FOUND', message: 'Data not found.', }); } return data; } catch (error) { logger.error("Error fetching data for id ${input.id}: ${error}"); if (error instanceof TRPCError) { throw error; // Re-throw known TRPC errors } throw new TRPCError({ code: 'INTERNAL_SERVER_ERROR', message: 'An unexpected error occurred.', }); } }), }); export type AppRouter = typeof appRouter; """ ### Anti-Patterns * Catching all exceptions and returning a generic error message, obscuring the root cause of the error. * Logging sensitive information, such as passwords or API keys. * Using "console.log" for logging in production. Use a dedicated logging library * Not implementing monitoring and alerting for critical errors. ## 7. Dependency Management and Security Audits ### Standards * **Do This:** Keep all dependencies up to date to patch security vulnerabilities. Use tools like "npm audit" or "yarn audit" to identify and fix vulnerabilities in your dependencies. * **Do This:** Regularly review and audit your application code for security vulnerabilities. Consider using static analysis tools or hiring a security consultant to perform penetration testing. * **Don't Do This:** Use outdated or unmaintained dependencies. * **Don't Do This:** Neglect security audits or rely solely on automated tools. Human review is essential to identify complex vulnerabilities. ### Explanation Dependencies can introduce security vulnerabilities if they are not properly maintained. Regularly updating dependencies and performing security audits can help identify and mitigate these risks. ### Code Example (N/A - Dependency Management is configuration-based) * **Using "npm audit":** """bash npm audit npm audit fix """ * **Using "yarn audit":** """bash yarn audit yarn audit fix """ ### Anti-Patterns * Ignoring security vulnerabilities reported by dependency audit tools. * Disabling security updates or pinning dependencies to specific versions indefinitely. * Not having a process for responding to security incidents. ## 8. Context Security ### Standards * **Do This:** Use the tRPC context to pass authenticated user information or other security-related data securely. * **Do This:** Ensure the context is constructed securely and avoid injecting untrusted data into it. Validate any data retrieved from the context within your procedures. * **Don't Do This:** Store sensitive data (like secrets) directly in the context if it's not needed for every procedure. Pass it explicitly where needed. * **Don't Do This:** Trust the context implicitly. Always validate the data within the context, especially when using it for authorization decisions. ### Explanation The tRPC context serves as a secure and efficient way to pass data to your procedures. Proper use of the context improves security and performance, while misuse can lead to vulnerabilities. ### Code Example """typescript import { publicProcedure, router, middleware } from './trpc'; import { TRPCError } from '@trpc/server'; // Example Authentication Middleware (simplified) const authMiddleware = middleware(async ({ ctx, next }) => { const userId = getUserIdFromHeaders(ctx.req.headers); // Replace with your actual authentication logic if (!userId) { throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Not authenticated' }); } return next({ ctx: { ...ctx, userId, // Add authenticated user ID to the context }, }); }); const protectedProcedure = publicProcedure.use(authMiddleware); export const appRouter = router({ // Protected procedure that accesses user ID from the context getUserData: protectedProcedure .query(async ({ ctx }) => { const userId = ctx.userId; // Access user ID from context const userData = await fetchUserData(userId); if (!userData) { throw new TRPCError({ code: 'NOT_FOUND', message: 'User data not found' }); } return userData; }), }); export type AppRouter = typeof appRouter; // Mock functions for demonstration purposes function getUserIdFromHeaders(headers: Headers): string | null { // Replace this with your actual authentication logic const authHeader = headers.get('authorization'); if (authHeader && authHeader.startsWith('Bearer ')) { // In a real implementation, you would verify the token and extract the user ID return 'mock-user-id'; } return null; } async function fetchUserData(userId: string): Promise<any> { // Replace this with your actual data fetching logic return { id: userId, name: 'Mock User', data: 'Sensitive Data' }; } """ ### Anti-Patterns * Injecting untrusted data directly into the context without validation. * Assuming the context is always present or contains valid data. * Overusing the context to pass data that is not essential to the security or operation of your procedures. * Failing to sanitize or validate data retrieved from the context before using it in your procedures, especially for authorization decisions. By adhering to these security best practices, you can build more secure and resilient tRPC applications that protect against common vulnerabilities and ensure the confidentiality, integrity, and availability of your data. Remember to stay informed about the latest security threats and adapt your practices accordingly.

# Core Architecture Standards for tRPC This document outlines the core architectural standards for tRPC applications. It provides guidelines on project structure, organization principles, and preferred patterns to ensure maintainability, performance, and security. These standards are based on the latest versions of tRPC and modern best practices. ## 1. Project Structure and Organization A well-structured project is crucial for maintainability and scalability. tRPC projects especially benefit from a clear separation of concerns, as they often involve both client and server-side code tightly integrated through type-safe APIs. ### 1.1. Standard Directory Structure Adopt a consistent directory structure to promote discoverability and maintainability. **Do This:** """ project-root/ ├── src/ │ ├── server/ # Server-side code │ │ ├── routers/ # tRPC routers │ │ │ ├── auth.ts # Authentication router │ │ │ ├── user.ts # User management router │ │ │ └── index.ts # Root router (combining all routers) │ │ ├── context.ts # tRPC context creation │ │ ├── trpc.ts # tRPC initialization and helpers │ │ └── index.ts # Server entry point │ ├── client/ # Client-side code (e.g., React components, hooks) │ │ ├── components/ # Reusable UI components │ │ ├── hooks/ # Custom React hooks │ │ ├── utils/ # Client-side utilities │ │ ├── trpc.ts # tRPC client initialization │ │ └── index.tsx # Client entry point │ ├── shared/ # Code shared between client and server │ │ ├── schemas/ # Zod schemas for data validation │ │ └── utils.ts # Shared utility functions │ ├── utils/ # General utility functions, types, or constants │ ├── app.d.ts # Type definitions. For Next.js, this is <root>/app/ │ └── index.ts # Main entry point ├── .env # Environment variables ├── package.json ├── tsconfig.json └── README.md """ **Don't Do This:** * Mixing client and server code within the same directory. * Placing all tRPC routers in a single file. * Lacking a clear separation of concerns in the codebase. * Ignoring a dedicated folder for reusable components and hooks. **Why This Matters:** A consistent structure makes it easier for developers to locate specific files and understand the project's overall organization. Separation of "/client" and "/server" code prevents accidental inclusion of server-side dependencies in client-side bundles. Shared code goes into "/shared" to minimise duplicated code. ### 1.2. Modular Router Design Break down your tRPC API into smaller, manageable routers based on domain or functionality. **Do This:** Create separate router files for different parts of your API (e.g., "auth.ts", "user.ts", "posts.ts"). """typescript // server/routers/auth.ts import { t } from '../trpc'; import { z } from 'zod'; export const authRouter = t.router({ getSession: t.procedure.query(({ ctx }) => { return ctx.session; }), createUser: t.procedure .input(z.object({ name: z.string(), email: z.string().email() })) .mutation(async ({ input }) => { // Create user in database return { success: true }; }), }); // server/routers/user.ts import { t } from '../trpc'; export const userRouter = t.router({ getUserById: t.procedure .input(z.string()) .query(async ({ input }) => { // Fetch user from database return { id: input, name: 'Example User' }; }), }); // server/routers/index.ts import { authRouter } from './auth'; import { userRouter } from './user'; import { t } from '../trpc'; export const appRouter = t.router({ auth: authRouter, user: userRouter, }); export type AppRouter = typeof appRouter; """ **Don't Do This:** * Defining all tRPC procedures in a single, monolithic router file. * Creating routers that are excessively large and difficult to navigate. * Failing to group related procedures into logical routers. **Why This Matters:** Modular routers improve code organization and make it easier to understand and maintain your API. It reduces the complexity of a single file and improves code navigation, making it simpler to understand the API's functions. ### 1.3. Shared Code Directory Centralize code shared between the client and server in a dedicated "shared/" directory. **Do This:** Use Zod schemas for data validation and define them in the "shared/schemas/" directory. """typescript // shared/schemas/user.ts import { z } from 'zod'; export const userSchema = z.object({ id: z.string(), name: z.string(), email: z.string().email(), }); export type User = z.infer<typeof userSchema>; """ """typescript // server/routers/user.ts import { t } from '../trpc'; import { userSchema } from '../../shared/schemas/user'; export const userRouter = t.router({ getUserById: t.procedure .input(z.string()) .query(async ({ input }) => { // Fetch user from database const user:User = {id: input, name: 'Example User', email:'test@email.com'}; //example for demo return userSchema.parse(user); //Validate the data }), }); """ """typescript // client/hooks/use-user.ts import { trpc } from '../trpc'; import {User} from '../../shared/schemas/user' export function useUser(userId: string) { const { data, isLoading, error } = trpc.user.getUserById.useQuery(userId); if(data){ const parsedData: User = data //Typesafe assertion. Typescript knows returned 'data' is the proper type! } return { user: data, isLoading, error }; } """ **Don't Do This:** * Duplicating validation schemas or types between the client and server. * Importing server-side code directly into client-side components (without going through tRPC). * Ignoring the concept of code sharing, which leads to repetition. **Why This Matters:** Sharing code reduces redundancy, ensures consistency between client and server, and improves maintainability by centralizing common logic. Using Zod schemas prevents type mismatches between client and server, and shared validation assures the data is correctly validated at BOTH points. ## 2. tRPC Context and Middleware tRPC context and middleware are critical for managing dependencies, authentication, and authorization. ### 2.1. Centralized Context Creation Create a centralized context function that provides access to dependencies like database connections, authentication status, and other shared resources. **Do This:** """typescript // server/context.ts import { inferAsyncReturnType } from '@trpc/server'; import { CreateNextContextOptions } from '@trpc/server/adapters/next'; /** * Creates context for an incoming request * @link https://trpc.io/docs/context */ export const createContext = async (opts: CreateNextContextOptions) => { const { req, res } = opts; // Get the session from the server using the unstable_getServerSession wrapper function const session = {user:{name:'Test User'}}; //Replace once authentication is setup properly return { session, req, res, prisma: {}, // Add your Prisma or database instance here }; }; export type Context = inferAsyncReturnType<typeof createContext>; """ **Don't Do This:** * Creating context directly within each procedure. * Missing including request and/or response objects, making it hard to get metadata. * Hardcoding dependencies within procedures, making them difficult to test. **Why This Matters:** Centralized context creation promotes code reuse and simplifies dependency injection. It also allows to easily add logging, instrumentation or other cross cutting concerns. This keeps individual procedures focused on their specific business logic. ### 2.2. Authentication and Authorization Middleware Implement authentication and authorization using tRPC middleware to secure your API endpoints. **Do This:** """typescript // server/trpc.ts import { initTRPC, TRPCError } from '@trpc/server'; import { Context } from './context'; const t = initTRPC.context<Context>().create(); const middleware = t.middleware; const isAuthed = middleware(async (opts) => { const { ctx } = opts; if (!ctx.session?.user) { throw new TRPCError({ code: 'UNAUTHORIZED' }); } return opts.next({ ctx: { user: ctx.session.user, }, }); }); export const router = t.router; export const publicProcedure = t.procedure; export const protectedProcedure = t.procedure.use(isAuthed); export const tRPC = t; //Export the t variable export const createCallerFactory = t.createCallerFactory; //helper to allow testing without http request export { t }; //Added to support older coding styles. """ """typescript // server/routers/user.ts import { protectedProcedure, router } from '../trpc'; export const userRouter = router({ getSecretMessage: protectedProcedure.query(() => { return "You are authenticated"; }), }); """ **Don't Do This:** * Performing authentication or authorization checks directly within procedures. * Exposing sensitive data or operations without proper authentication and authorization. * Using insecure methods to store or transmit authentication credentials. **Why This Matters:** tRPC middleware enables you to centralize authentication and authorization logic. Securing your API endpoints prevents unauthorized access to sensitive data and operations. ### 2.3. Custom Middleware for Logging and Error Handling Use custom middleware to add logging and error handling to your tRPC API. **Do This:** """typescript import { initTRPC, TRPCError } from '@trpc/server'; import { Context } from './context'; const t = initTRPC.context<Context>().create(); const middleware = t.middleware; const logger = middleware(async (opts) => { //Middleware for logging console.log('┌── tRPC Request'); console.log("│ Path: ${opts.path}"); console.log("│ Input: ${JSON.stringify(opts.input)}"); const result = await opts.next(); console.log('└── tRPC Response'); if (result.ok) { console.log(' │ OK:', result.data); } else { console.log(' │ Error:', result.error); } return result; }); const tRPC = initTRPC.context<Context>().middleware(logger).create(); export const publicProcedure = tRPC.procedure; const isAuthed = middleware(async (opts) => { //...authentication logic... }) export const router = t.router; export const protectedProcedure = t.procedure.use(isAuthed); export {tRPC} """ **Don't Do This:** * Relying solely on client-side logging or error handling. * Missing capturing errors in middleware, resulting in unhandled exceptions. * Missing including request and/or response, making it difficult to triage issues. * Logging sensitive information like passwords or API keys. **Why This Matters:** Middleware enables you to centralize logging and error handling logic. Centralized logging facilitates monitoring and debugging and error handling improves the reliability of your API. ## 3. Data Validation with Zod Zod schemas are essential for validating data passed to and from tRPC procedures. ### 3.1. Strict Input Validation Use Zod schemas to strictly validate all input data to your tRPC procedures. **Do This:** """typescript // server/routers/user.ts import { z } from 'zod'; import {protectedProcedure, router } from '../trpc'; const userCreateSchema = z.object({ name: z.string().min(2).max(50), email: z.string().email(), }); export const userRouter = router({ createUser: protectedProcedure .input(userCreateSchema) .mutation(async ({ input }) => { // Create user in database using validated input return { success: true }; }), }); """ **Don't Do This:** * Skipping input validation, which can lead to data corruption and security vulnerabilities. * Relying solely on client-side validation, as it can be bypassed. * Using weak or incomplete validation schemas. **Why This Matters:** Strict input validation prevents invalid data from entering your application. This improves data integrity and prevents common security vulnerabilities, such as injection attacks. ### 3.2. Output Validation and Transformation Use Zod schemas to validate and transform the output data from your tRPC procedures. **Do This:** """typescript // server/routers/user.ts import { z } from 'zod'; import { protectedProcedure, router } from '../trpc'; const userSchema = z.object({ id: z.string(), name: z.string(), email: z.string().email(), }); export const userRouter = router({ getUserById: protectedProcedure .input(z.string()) .output(userSchema) //This is relatively new, so ensure your tRPC is up to date. .query(async ({ input }) => { // Fetch user from database const user = { id: input, name: 'Example User', email: 'test@example.com' }; return userSchema.parse(user); // Validate the data }), }); """ **Don't Do This:** * Returning raw data without validation or transformation. * Assuming that data returned from the database or other sources is always valid. * Skipping output validation, especially for public APIs. **Why This Matters:** Validating output ensures that the data returned by your API is consistent with your schema. This improves data integrity, prevents unexpected errors on the client-side and provides type safety throughout your application. Output validation and Transformation is now built into tRPC as of v10.44.0. ### 3.3. Reusable Schemas Create reusable Zod schemas for common data structures, such as user profiles, posts, and comments, and store them in the "/shared" directory. **Do This:** """typescript // shared/schemas/user.ts import { z } from 'zod'; export const userSchema = z.object({ id: z.string(), name: z.string(), email: z.string().email(), }); export type User = z.infer<typeof userSchema>; """ **Don't Do This:** * Duplicating schemas across multiple routers or components. * Defining complex schemas directly within procedures, which can make them difficult to maintain. * Failing to create reusable schemas for common data structures. **Why This Matters:** Reusable schemas reduce redundancy, ensure consistency across your application and improve maintainability by centralizing schema definitions. DRY: Don't Repeat Yourself. ## 4. Testing Robust testing is essential for maintaining the quality of your tRPC API. ### 4.1. Unit Testing for Procedures Write unit tests for individual tRPC procedures to ensure they function correctly. **Do This:** """typescript // server/routers/user.test.ts import { appRouter } from './index'; // Import your root router import { createCallerFactory } from '../trpc'; import { describe, expect, it } from 'vitest'; describe('User Router', () => { it('should get a user by ID', async () => { const caller = createCallerFactory({} as any)( { user: {name: 'test user'} }); //Mock Context const result = await caller.user.getUserById("123") expect(result.name).toBe('Example User'); expect(result.id).toBe('123'); }); }); """ **Don't Do This:** * Skipping unit tests for tRPC procedures. * Writing tests that are too broad or too focused on implementation details. * Ignoring edge cases or error conditions in your tests. **Why This Matters:** Unit tests ensure that individual procedures function correctly. Testing mitigates regressions, reduces bugs, and improves the overall reliability of your API. ### 4.2. Integration Testing for Routers Write integration tests to verify the interaction between different tRPC routers and procedures. **Do This:** """typescript // server/routers/index.test.ts import { appRouter } from './index'; // Import your root router import { createCallerFactory } from '../trpc'; import { describe, expect, it } from 'vitest'; describe('Root Router', () => { it('should call protected procedure', async () => { const caller = createCallerFactory({} as any)( { user: {name: 'test user'} }); //Mock the authentication. const result = await caller.user.getSecretMessage(); expect(result).toBe('You are authenticated'); }); }); """ **Don't Do This:** * Relying solely on unit tests, which may not catch integration issues. * Writing integration tests that are too complex or difficult to maintain. * Failing to test the interaction between different routers and procedures. **Why This Matters:** Integration tests verify the interaction between different parts of your API. This prevents integration issues, ensures that routers and procedures work together correctly and improves the overall stability of your application. ### 4.3. End-to-End Testing End-to-end (E2E) tests ensure that your entire application, including your tRPC API, works as expected from the user's perspective. Because tRPC is inherently full stack, E2E tests are extremely valuable. **Do This:** * Use tools like Playwright or Cypress to write E2E tests that simulate user interactions with your application. * Test common user flows, such as login, data entry, and form submission. * Verify that data is correctly displayed and persisted in the database. **Don't Do This:** * Skipping E2E tests, which may miss critical integration issues. * Writing E2E tests that are too brittle or difficult to maintain. * Failing to test the entire application flow from the user's perspective. **Why This Matters:** E2E tests verify that your entire application works as expected. Testing improves user experience, reduces the risk of critical bugs in production and ensures the overall quality of your application. Even for teams that don't fully practice TDD, E2E testing can be tremendously helpful. ## 5. Performance Optimization Optimize your tRPC API for performance to ensure a smooth and responsive user experience. ### 5.1. Data Fetching Strategies Use efficient data fetching strategies to minimize the number of database queries and network requests. **Do This:** * Use techniques like query batching and caching to reduce the number of database queries. * Implement data pagination and filtering to retrieve only the necessary data. * Use appropriate indexes in your database to optimize query performance. **Don't Do This:** * Fetching unnecessary data, which can slow down your API and increase network traffic. * Performing multiple database queries when a single query would suffice. * Ignoring the performance impact of database queries and network requests. **Why This Matters:** Optimized data fetching improves API performance, reduces network traffic, and provides a better user experience. Carefully consider if batching, caching, pagination, or other optimizations might be beneficial in each specific case. ### 5.2. Caching Strategies Implement caching strategies to reduce the load on your server and improve response times. **Do This:** * Use client-side caching to store frequently accessed data in the user's browser. * Implement server-side caching using tools like Redis or Memcached to store API responses. * Use appropriate cache invalidation strategies to ensure that cached data is up-to-date. **Don't Do This:** * Caching sensitive data without proper security measures. * Using overly aggressive caching strategies that can lead to stale data. * Ignoring the performance benefits of caching. **Why This Matters:** Caching reduces the load on servers by avoiding unneccessary processing when data doesn't change frequently. This improves API performance and response times. You must implement appropriate cache invalidation to ensure clients are looking at updated data. ### 5.3. Code Splitting Use code splitting to reduce the initial load time of your client-side application. **Do This:** * Split your code into smaller bundles that can be loaded on demand. * Use dynamic imports to load components and modules only when they are needed. * Optimize your build process to minimize the size of your JavaScript bundles. **Don't Do This:** * Creating large, monolithic JavaScript bundles that can slow down your application. * Ignoring the performance benefits of code splitting. * Over complicating code splitting, which can result in increased complexity and maintenance overhead. **Why This Matters:** Code splitting reduces the initial load time of the application. This significantly improves the user experience, especially on mobile devices, and reduces the time to first meaningful paint. ## 6. Security Best Practices Implement security best practices to protect your tRPC API from common vulnerabilities. ### 6.1. Input Validation Strictly validate all input data to prevent injection attacks and other security vulnerabilities (as covered in section 3.1). ### 6.2. Authentication and Authorization Implement robust authentication and authorization mechanisms to protect your API endpoints (as covered in section 2.2). ### 6.3. Rate Limiting Implement rate limiting to prevent abuse and denial-of-service attacks. **Do This:** * Limit the number of requests that a user or IP address can make within a certain time period. * Use tools like Redis or Memcached to store rate limiting data. * Monitor your API for suspicious activity and adjust rate limits accordingly. **Don't Do This:** * Failing to implement rate limiting, which can leave your API vulnerable to abuse. * Using overly restrictive rate limits that can negatively impact legitimate users. * Ignoring the importance of rate limiting as a security measure. **Why This Matters:** Rate limiting prevents abuse, protects your API from denial-of-service attacks, and improves the overall security and stability of your application. ### 6.4. CORS Configuration Configure Cross-Origin Resource Sharing (CORS) to prevent unauthorized access to your API from different domains. **Do This:** * Specify the allowed origins in your CORS configuration. * Use wildcard origins sparingly, as they can create security vulnerabilities. * Ensure that your CORS configuration is properly configured in your production environment. **Don't Do This:** * Disabling CORS entirely, which can leave your API vulnerable to cross-site scripting (XSS) attacks. * Using overly permissive CORS configurations that allow unauthorized access to your API. * Ignoring the importance of CORS as a security measure. **Why This Matters:** CORS prevents unauthorized access, protects your API from cross-site scripting (XSS) attacks, and improves the overall security of your application. This document provides a foundation for establishing coding standards for tRPC applications. By adhering to these guidelines, development teams can build robust, maintainable, and secure APIs. As tRPC and related technologies evolve, these standards should be periodically reviewed and updated to reflect the latest best practices.

# Component Design Standards for tRPC This document outlines the coding standards specifically for designing reusable and maintainable components within tRPC applications. These guidelines focus on leveraging the latest tRPC features and best practices to promote code clarity, prevent common pitfalls, and optimize performance. ## 1. Principles of Reusable tRPC Components ### 1.1 Abstraction and Encapsulation * **Do This:** Abstract complex logic into reusable functions and modules. Apply this at all scales, from individual helpers used in multiple procedures to entirely separate routers that are composed together into your server. * **Why:** Abstraction reduces code duplication and improves readability. Encapsulation hides implementation details, minimizing the impact of changes on other parts of the application. """typescript // Good: Abstracted helper function const validateEmail = (email: string): boolean => { const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; // More robust regex should be used in prod. return emailRegex.test(email); }; const userRouter = t.router({ createUser: t.procedure .input(z.object({ email: z.string() })) .mutation(async ({ input }) => { if (!validateEmail(input.email)) { throw new TRPCError({ code: 'BAD_REQUEST', message: 'Invalid email format' }); } // ... rest of create user logic }), }); """ * **Don't Do This:** Embed the same complex logic repeatedly throughout your tRPC procedures. Avoid exposing internal implementation details of your procedures directly to the client. """typescript // Bad: Duplicated validation logic const userRouter = t.router({ createUser: t.procedure .input(z.object({ email: z.string() })) .mutation(async ({ input }) => { const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!emailRegex.test(input.email)) { throw new TRPCError({ code: 'BAD_REQUEST', message: 'Invalid email format' }); } // ... rest of create user logic }), updateUserEmail: t.procedure .input(z.object({ id: z.string(), email: z.string() })) .mutation(async ({ input }) => { const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!emailRegex.test(input.email)) { throw new TRPCError({ code: 'BAD_REQUEST', message: 'Invalid email format' }); } // ... rest of update user logic }), }); """ ### 1.2 Single Responsibility Principle (SRP) * **Do This:** Design components (procedures, routers, helper functions) to have a single, well-defined purpose. * **Why:** SRP makes components easier to understand, test, and modify. Changes to one aspect of the component will be less likely to affect other parts of the system. """typescript // Good: Separate service for interacting with the database import { prisma } from './db'; // Assuming you are using Prisma/ORM const userService = { getUserById: async (id: string) => { return await prisma.user.findUnique({ where: { id } }); }, createUser: async (email: string) => { return await prisma.user.create({ data: { email } }); }, // ... other user-related database operations }; const userRouter = trpc.router({ getUser: t.procedure .input(z.object({ id: z.string() })) .query(async ({ input }) => { return userService.getUserById(input.id); }), createUser: t.procedure .input(z.object({ email: z.string() })) .mutation(async ({ input }) => { return userService.createUser(input.email); }), }); """ * **Don't Do This:** Create overly complex procedures that handle multiple unrelated tasks. """typescript // Bad: Combining data fetching and email sending in single procedure const userRouter = t.router({ createUserAndSendWelcomeEmail: t.procedure .input(z.object({ email: z.string() })) .mutation(async ({ input }) => { const user = await prisma.user.create({data: {email: input.email}}); // Complex email sending logic here... return user; }), }); """ ### 1.3 Composition over Inheritance * **Do This:** Favor composing smaller, reusable functions or modules into larger components rather than using inheritance. In tRPC, this often manifests as composing multiple routers together via "mergeRouters". * **Why:** Composition provides greater flexibility and reduces the risk of creating tightly coupled systems. """typescript // Good: Composing routers const authRouter = trpc.router({ getSession: trpc.procedure.query(() => { // ... authentication logic }), }); const userRouter = trpc.router({ getUser: trpc.procedure .input(z.object({id: z.string()})) .query(async ({input, ctx}) => { //Make sure user is authenticated if(!ctx.session) { throw new TRPCError({ code: 'UNAUTHORIZED' }); } return await prisma.user.findUnique({where: {id: input.id}}); }), }); const appRouter = trpc.mergeRouters(authRouter, userRouter); // Export type definition of API export type AppRouter = typeof appRouter; """ * **Don't Do This:** Attempt to create deeply nested hierarchies of routers or procedures to achieve code reuse if composition would be more appropriate. Avoid creating "base" routers that are only meant to be extended. ## 2. tRPC Router Design ### 2.1 Router Naming and Organization * **Do This:** Use descriptive names for routers that clearly indicate their domain or purpose (e.g., "userRouter", "productRouter", "authRouter"). Organize routers into logical modules based on functionality. * **Why:** Clear naming and organization improve code discoverability and maintainability. """typescript // Good: Clear router organization // src/server/routers/user.ts export const userRouter = t.router({ /* ... */ }); // src/server/routers/product.ts export const productRouter = t.router({ /* ... */ }); // src/server/routers/auth.ts export const authRouter = t.router({ /* ... */ }); """ * **Don't Do This:** Use generic or ambiguous names for routers (e.g., "router1", "api"). Place routers in arbitrary locations without a clear organizational structure. ### 2.2 Context Management * **Do This:** Utilize the tRPC context effectively to share data and dependencies across procedures within a router. Keep the context lean and focused on essential information. * **Why:** Sharing context reduces code duplication and improves performance by avoiding redundant data fetching. """typescript // Good: Using context to share database connection import { inferAsyncReturnType } from '@trpc/server'; import { prisma } from './db'; // src/server/context.ts export const createContext = async () => { return { prisma, }; }; type Context = inferAsyncReturnType<typeof createContext>; export const t = trpc.context<Context>().create(); const userRouter = t.router({ getUser: t.procedure .input(z.object({ id: z.string() })) .query(async ({ input, ctx }) => { return await ctx.prisma.user.findUnique({ where: { id: input.id } }); }), }); """ * **Don't Do This:** Pass data or dependencies as arguments to every procedure, especially if they are already available in the context. Overload the context with unnecessary information. ### 2.3 Input Validation and Transformation * **Do This:** Use Zod schemas to rigorously validate and transform input data for all tRPC procedures. Define schemas that accurately reflect the expected data structure and constraints. * **Why:** Input validation prevents errors, protects against malicious input, and ensures type safety. Transformation allows you to sanitize and normalize data before processing it. """typescript // Good: Validating and transforming input with Zod import { z } from 'zod'; const userRouter = t.router({ createUser: t.procedure .input( z.object({ email: z.string().email(), name: z.string().min(2).max(50), }) ) .mutation(async ({ input }) => { // input is guaranteed to be valid and transformed const { email, name } = input; // Destructure to use type-safe values return await prisma.user.create({ data: { email, name } }); }), }); """ * **Don't Do This:** Skip input validation or rely on implicit type coercion. Define overly permissive schemas that allow invalid data to reach your application logic. Avoid sanitizing or transforming data that comes from the client. ### 2.4 Error Handling * **Do This:** Use "TRPCError" to throw appropriate error codes for different scenarios in your tRPC procedures. Implement centralized error handling to log errors, notify developers, and provide informative error messages to the client. * **Why:** Proper error handling improves the user experience, helps debug issues, and enhances the security of your application. """typescript // Good: Using TRPCError with appropriate error codes import { TRPCError } from '@trpc/server'; const userRouter = t.router({ getUser: t.procedure .input(z.object({ id: z.string() })) .query(async ({ input, ctx }) => { const user = await ctx.prisma.user.findUnique({ where: { id: input.id } }); if (!user) { throw new TRPCError({ code: 'NOT_FOUND', message: "User with id ${input.id} not found", }); } return user; }), }); """ * **Don't Do This:** Throw generic errors or uncaught exceptions. Return plain strings or error objects without a standard format. ### 2.5 Middleware * **Do This:** Use tRPC middleware to implement cross-cutting concerns such as authentication, authorization, logging, and data caching. Create reusable middleware functions that can be applied to multiple procedures or routers. Leverage the "unstable_allowGet" option for queries protected by middleware. * **Why:** Middleware promotes code reuse and reduces duplication. """typescript // Good: Authentication middleware const isAuthed = t.middleware(({ ctx, next }) => { if (!ctx.user) { throw new TRPCError({ code: 'UNAUTHORIZED' }); } return next({ ctx: { user: ctx.user, }, }); }); const authedProcedure = t.procedure.use(isAuthed); const userRouter = t.router({ getSecret: authedProcedure.query(({ ctx }) => { return "This is the secret"; }), }); """ * **Don't Do This:** Embed authentication or authorization logic directly in every procedure. Create overly complex middleware functions that perform multiple unrelated tasks. ## 3. tRPC Procedure Design ### 3.1 Query vs. Mutation * **Do This:** Use queries for read-only operations that do not modify data. Use mutations for operations that create, update, or delete data. * **Why:** Distinguishing between queries and mutations improves code clarity, optimizes performance, and enables better caching strategies. """typescript // Good: Using queries for read operations and mutations for write operations const userRouter = t.router({ getUser: t.procedure .input(z.object({ id: z.string() })) .query(async ({ input, ctx }) => { // Query return await ctx.prisma.user.findUnique({ where: { id: input.id } }); }), updateUser: t.procedure .input(z.object({ id: z.string(), email: z.string().email() })) .mutation(async ({ input, ctx }) => { // Mutation return await ctx.prisma.user.update({ where: { id: input.id }, data: { email: input.email }, }); }), }); """ * **Don't Do This:** Use queries to perform data modifications or mutations to fetch data. ### 3.2 Optimistic Updates * **Do This:** For mutations that update UI state, consider using optimistic updates to provide a smoother user experience. * **Why:** Optimistic updates make the UI feel more responsive by immediately reflecting the changes made by the user, even before the server confirms the update. """typescript // Example (React component): import { useMutation } from '@trpc/react-query'; import { useState } from 'react'; const Component = () => { const [text, setText] = useState('initial Value'); const {mutate} = useMutation('example.updateText', { onMutate: async (newText) => { // Cancel any outgoing refetches (so they don't overwrite our optimistic update) // await queryClient.cancelQueries(['example.getText']) setText(newText); }, }); return ( <div> <input type="text" value={text} onChange={(e) => { setText(e.target.value); mutate(e.target.value); }} /> </div> ); }; """ * **Don't Do This:** Neglect to handle potential errors or conflicts when using optimistic updates. ### 3.3 Batching and Caching * **Do This:** Consider batching multiple requests into a single request to reduce network overhead. Implement server-side and client-side caching to improve performance. Use tRPC utilities or libraries like "@trpc/react-query" for efficient caching. * **Why:** Batching and caching can significantly improve the performance and scalability of your application, especially for frequently accessed data. * **Don't Do This:** Over-cache data or cache sensitive information. Neglect to invalidate the cache when data changes. ## 4. Code Style and Formatting * **Do This:** Follow a consistent code style guide (e.g., Prettier, ESLint) to ensure code uniformity. Use meaningful names for variables, functions, and components. Provide clear and concise comments to explain complex logic. * **Why:** Consistent code style improves readability and maintainability. Clear names and comments make it easier to understand the code. * **Don't Do This:** Use inconsistent code formatting or ambiguous names. Write overly verbose or unhelpful comments. ## 5. Testing * **Do This:** Write unit tests for individual tRPC procedures and integration tests for complete workflows. Mock dependencies to isolate components during testing. Use tools like Jest and Supertest for testing tRPC APIs. * **Why:** Testing ensures that your tRPC APIs function correctly and reliably. * **Don't Do This:** Neglect to write tests or write incomplete or ineffective tests. ## 6. Security Considerations * **Do This:** Protect your tRPC APIs against common security vulnerabilities such as injection attacks, cross-site scripting (XSS), and cross-site request forgery (CSRF). Sanitize user input, validate data on the server-side, and implement proper authentication and authorization mechanisms. Rate limit your tRPC endpoints to prevent abuse. * **Why:** Security vulnerabilities can compromise the integrity and confidentiality of your application and data. * **Don't Do This:** Expose sensitive data through your tRPC APIs. Store sensitive data in client-side cookies or local storage. These standards provide a foundation for building robust, maintainable, and secure tRPC applications. Adhering to these guidelines will promote collaboration, reduce errors, and improve the overall quality of your code.

# State Management Standards for tRPC This document outlines the best practices for managing state in applications using tRPC. It covers strategies for data flow, reactivity, and efficient state management, with a focus on how these principles apply specifically within the tRPC ecosystem. ## 1. Architecture and Principles ### 1.1. Centralized vs. Decentralized State **Standard:** Prefer a centralized state management solution for global application state, but consider decentralized, component-level state for isolated UI elements. * **Do This:** Use libraries like Zustand, Jotai, or Redux for managing application-wide data accessed by multiple components. * **Don't Do This:** Avoid prop drilling large amounts of data through the component tree. Don't tightly couple individual components with direct data dependencies. * **Why:** Centralized state enhances predictability, simplifies debugging, and facilitates data consistency. Decentralized state improves component isolation and reusability. **Example (Centralized State with Zustand):** """typescript import { create } from 'zustand'; interface UserState { user: { id: string; name: string } | null; setUser: (user: { id: string; name: string } | null) => void; } const useUserStore = create<UserState>((set) => ({ user: null, setUser: (user) => set({ user }), })); export default useUserStore; // In a tRPC procedure: import { publicProcedure, router } from './trpc'; import { z } from 'zod'; export const appRouter = router({ getUser: publicProcedure .input(z.object({ userId: z.string() })) .query(async ({ input }) => { // Simulate fetching user from DB const user = { id: input.userId, name: "Example User" }; return user; // Return data to the client // This data can later be stored in Zustand }), }); // Usage in a React Component: import useUserStore from './userStore'; import { trpc } from './utils/trpc'; // Ensure this references your tRPC client function UserProfile({ userId }: { userId: string }) { const { user, setUser } = useUserStore(); const { data, isLoading } = trpc.getUser.useQuery({ userId: userId }, { onSuccess: (data) => { setUser(data); // Update Zustand state with tRPC response }, }); if (isLoading) return <p>Loading...</p>; if (!user) return <p>No user found</p>; return ( <div> <h1>{user.name}</h1> <p>ID: {user.id}</p> </div> ); } export default UserProfile; """ ### 1.2. Data Flow with tRPC **Standard:** Design data flows originating from tRPC procedures, updating the client-side state Reactively. * **Do This:** Use "useQuery" hooks from "@trpc/react-query" to fetch data, and upon successful retrieval, update your state management solution. Trigger mutations via "useMutation" to modify data, and invalidate queries as needed to refresh the cache. * **Don't Do This:** Directly manipulate server-side data from client-side components. Avoid mixing tRPC calls directly in complex component logic, keep them separate. * **Why:** tRPC ensures type safety and prevents inconsistencies between server and client. Leveraging "useQuery" and "useMutation" promotes client-side reactivity upon data changes, and it makes invalidating queries when mutations occur much easier. **Example (Data Flow with tRPC and "useMutation"):** """typescript // tRPC Router (server) import { publicProcedure, router } from './trpc'; import { z } from 'zod'; export const appRouter = router({ updateUserName: publicProcedure .input(z.object({ userId: z.string(), newName: z.string() })) .mutation(async ({ input }) => { // In a real app, you'd update a database here. console.log("Updating user ${input.userId} name to ${input.newName}"); return {userId: input.userId, newName: input.newName}; // Simulate a DB update result }), }); // React Component (client) import { trpc } from './utils/trpc'; // Ensure this references your tRPC client function UpdateUserName({ userId }: { userId: string }) { const { mutate: updateName, isLoading, isError } = trpc.updateUserName.useMutation({ onSuccess: (data) => { // Invalidate the 'getUser' query to refetch fresh data. trpc.getUser.invalidate({ userId: data.userId }); }, }); const [newName, setNewName] = React.useState(''); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); updateName({ userId: userId, newName: newName }); }; if (isLoading) return <p>Updating...</p>; if (isError) return <p>Error updating name.</p>; return ( <form onSubmit={handleSubmit}> <input type="text" value={newName} onChange={(e) => setNewName(e.target.value)} placeholder="New Name" /> <button type="submit">Update Name</button> </form> ); } export default UpdateUserName; """ ### 1.3. Optimistic Updates **Standard:** Implement optimistic updates to provide a responsive user experience, but ensure proper error handling to revert changes when necessary. * **Do This:** Temporarily update the UI state with the anticipated outcome of a mutation. In the "onMutate" callback of "useMutation", store the previous query data, and revert to it if the mutation fails. * **Don't Do This:** Implement optimistic updates without handling potential errors or inconsistencies. * **Why:** Optimistic updates make applications feel faster from the user's perspective. Reverting on error maintains data integrity. **Example (Optimistic Updates with "useMutation"):** """typescript // React Component (client) import { trpc } from './utils/trpc'; // Ensure this references your tRPC client function UpdateLikeCount({ postId }: { postId: string }) { const utils = trpc.useContext(); // Use trpc context const { mutate: addLike, isLoading } = trpc.addLike.useMutation({ onMutate: async (variables) => { // Cancel any outgoing refetches (so they don't overwrite our optimistic update) await utils.cancelQueries(['post.getPost', { postId: variables.postId }]); // Snapshot the previous value const previousPost = utils.getQueryData(['post.getPost', { postId: variables.postId }]); // Optimistically update to the new value utils.setQueryData(['post.getPost', { postId: variables.postId }], (old: any) => { if (!old) return old; return { ...old, likes: old.likes + 1 }; // Assuming "likes" is a number }); // Return a context object with the snapshotted value return { previousPost }; }, onError: (_err, variables, context) => { // If the mutation fails, roll back to the previous value utils.setQueryData(['post.getPost', { postId: variables.postId }], (context as any)?.previousPost); }, onSettled: (data, error, variables) => { // Always refetch query after error or success: utils.invalidateQueries(['post.getPost', { postId: variables.postId }]); }, }); return ( <button onClick={() => addLike({ postId: postId })} disabled={isLoading}> Like </button> ); } """ ## 2. Reactivity and Caching ### 2.1. React Query Integration **Standard:** Leverage React Query's caching and invalidation mechanisms integrated with tRPC for efficient data fetching and state synchronization. * **Do This:** Use "useQuery" to fetch data and automatically cache responses. Use "invalidateQueries" after mutations to automatically refetch invalidated data, keeping the state current. Configure "staleTime" and "cacheTime" appropriately for different data types. * **Don't Do This:** Neglect React Query's caching features which can lead to unnecessary API requests. Manually manage cache invalidation. * **Why:** React Query simplifies data management, eliminates boilerplate code, and optimizes performance by caching API responses. **Example (Caching Configuration):** """typescript // Wrap your whole app in a QueryClientProvider import { QueryClient, QueryClientProvider } from '@tanstack/react-query' const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 60 * 1000, // 1 minute cacheTime: 5 * 60 * 1000, // 5 minutes refetchOnWindowFocus: false, retry: false, }, }, }) function App() { return ( <QueryClientProvider client={queryClient}> {/* your app */} </QueryClientProvider> ) } """ ### 2.2. Selective Query Invalidation **Standard:** Invalidate only the specific queries affected by a mutation to avoid unnecessary data refetching. * **Do This:** Use "trpc.invalidateQueries" with specific query keys after a mutation completes. * **Don't Do This:** Invalidate all queries globally after every mutation, as this will cause performance issues for larger applications. * **Why:** Selective invalidation minimizes server load and improves application responsiveness. **Example (Specific Query Invalidation):** """typescript // React Component (client) import { trpc } from './utils/trpc'; // Ensure this references your tRPC client function DeletePost({ postId }: { postId: string }) { const utils = trpc.useContext(); const { mutate: deletePost, isLoading, isError } = trpc.deletePost.useMutation({ onSuccess: () => { // Invalidate the posts list query to refresh the list utils.post.getAllPosts.invalidate(); // Optionally invalidate a specific post query as well utils.post.getPost.invalidate({ postId: postId }); }, }); if (isLoading) return <p>Deleting...</p>; if (isError) return <p>Error deleting the post.</p>; return ( <button onClick={() => deletePost({ postId: postId })}>Delete</button> ); } """ ### 2.3. Prefetching **Standard:** Use prefetching strategically to load data before it's needed, improving the user experience. * **Do This:** Use React Query's "queryClient.prefetchQuery" to load data for routes the user is likely to visit soon. * **Don't Do This:** Prefetch too much data upfront since this can degrade initial load times. * **Why:** Prefetching can make transitions between pages or components feel instantaneous. **Example (Prefetching in next.js "getServerSideProps"):** """typescript // pages/posts/[id].tsx import { GetServerSideProps } from 'next'; import { trpc } from '../../utils/trpc'; import { appRouter } from '../../server/routers/_app'; import { createTRPCContext } from '../../server/trpc'; export const getServerSideProps: GetServerSideProps = async (context) => { const postId = context.params?.id as string; const trpcContext = await createTRPCContext({ req: context.req, res: context.res }); const caller = appRouter.createCaller(trpcContext); // Prefetch the post data await trpc.post.getPost.prefetch({ postId: postId }); return { props: { trpcState: await trpc.getAllPosts.ssr(), }, }; }; function PostPage({ postId }: { postId: string }) { const { data, isLoading } = trpc.post.getPost.useQuery({ postId: postId }); if (isLoading) return <p>Loading...</p>; if (!data) return <p>Post not found</p>; return ( <div> <h1>{data.title}</h1> <p>{data.content}</p> </div> ); } export default PostPage; """ ## 3. Implementation Details ### 3.1. Avoiding Common Pitfalls **Standard:** Steer clear of common mistakes when integrating state management with tRPC. * **Don't Do This:** * Over-fetching or under-fetching data with poorly defined queries. * Ignoring error states from "useQuery" and "useMutation". * Creating race conditions when updating state after a mutation. * Directly mutating the query cache without using provided methods (e.g., "setQueryData"). This can lead to unexpected behaviours. * Deeply nesting tRPC calls inside component logic. This can make debugging very challenging. Prefer lifting the tRPC call outside component logic. Especially do not use "await trpc.myProc.mutate({})" inside a component's render cycle. ### 3.2. Handling Complex State with tRPC **Standard:** Address complex state management scenarios within tRPC applications thoughtfully. * **Do This:** * Utilize custom React Query hooks to encapsulate complex data fetching and transformation logic. * Break down large datasets into smaller, manageable units. * Use dependent queries to fetch data only when necessary. * If needing to call a tRPC procedure *within* another tRPC procedure (which is quite rare), consider using "inferAsyncReturnType" to correctly type the response for the caller. **Example (Dependent Queries):** """typescript // React Component (client) import { trpc } from '../../utils/trpc'; // Ensure this references your tRPC client function UserPosts({ userId }: { userId: string }) { // Fetch user details const { data: user, isLoading: isUserLoading } = trpc.user.getUser.useQuery({ userId: userId }); // Fetch user's posts, but only if user details have loaded const { data: posts, isLoading: isPostsLoading } = trpc.post.getPostsByUser.useQuery({ userId: userId }, { enabled: !!user, // Only run this query if 'user' is not null/undefined }); if (isUserLoading) return <p>Loading user...</p>; if (!user) return <p>User not found</p>; if (isPostsLoading) return <p>Loading posts...</p>; return ( <div> <h2>{user.name}'s Posts</h2> {posts?.map(post => ( <div key={post.id}> <h3>{post.title}</h3> <p>{post.content}</p> </div> ))} </div> ); } export default UserPosts; """ ### 3.3. Secure State Management **Standard:** Implement security best practices when working with sensitive data in your application state. * **Do This:** * Never store sensitive information directly in the client-side state if it doesn't need to be there. Only store the data required for the currently rendered UI. * Use environment variables and secure configuration to handle API keys and sensitive credentials. * Implement proper authentication and authorization on the server-side to prevent unauthorized access to data. * Sanitize data received from the server before storing it in the state. * Use HTTPS to encrypt data transmitted between the client and the server. **Example (Safe data retrieval):** """typescript // tRPC Router (server) import { publicProcedure, router, protectedProcedure } from './trpc'; import { z } from 'zod'; export const appRouter = router({ getSensitiveData: protectedProcedure // Only accessible if authenticated .query(async ({ ctx }) => { if (!ctx.auth.userId) { // Double check, just to be safe throw new Error("Not authenticated"); } // Retrieve data, ensuring user has access rights const sensitiveData = await getSensitiveDataFromDB(ctx.auth.userId); return sensitiveData; }), }); """ This coding standards document provides a strong foundation for building robust, maintainable, and performant tRPC applications with well-managed state. These standards will help developers, and AI coding assistants alike, write better tRPC code with a focus on state management best practices. Remember to review and update this document regularly as the tRPC ecosystem evolves.

# Testing Methodologies Standards for tRPC This document outlines the testing methodologies standards for tRPC applications. It covers unit, integration, and end-to-end testing strategies, tailored to the specifics of tRPC. Adhering to these standards promotes maintainability, reliability, and confidence in your tRPC applications. ## 1. General Testing Principles for tRPC ### 1.1. Write Tests Early and Often * **Do This:** Embrace Test-Driven Development (TDD) or Behavior-Driven Development (BDD) principles. Write tests before or alongside your tRPC procedure implementations. * **Don't Do This:** Postpone testing until after the implementation is complete. This leads to rushed tests, poor coverage, and increased debugging time. **Why:** Writing tests early forces you to think about the expected behavior and API design upfront. It also helps catch regressions during development. ### 1.2. Aim for High Test Coverage * **Do This:** Strive for high code coverage (80% or higher) across your tRPC procedures and associated logic. Use coverage tools like "nyc" or "c8" to measure coverage. * **Don't Do This:** Equate high coverage with perfect testing. Focus on testing critical business logic and edge cases. **Why:** High coverage reduces the risk of undetected bugs. ### 1.3. Focus on Meaningful Assertions * **Do This:** Write assertions that verify the core behavior and data transformations of your tRPC procedures. * **Don't Do This:** Write superficial assertions that simply check if the procedure runs without errors. Assertions should validate the returned data structure and individual elements. **Why:** Meaningful assertions guarantee that your procedures behave as expected. ### 1.4. Keep Tests Independent and Isolated * **Do This:** Design tests that can be run independently of each other. Use mocking and stubbing to isolate your tRPC procedures from external dependencies. * **Don't Do This:** Create tests that rely on shared state or depend on the execution order of other tests. **Why:** Independent tests are easier to debug and maintain. ### 1.5. Keep Tests Fast * **Do This:** Optimize your test suite for speed. Parallelize tests when possible and avoid unnecessary delays. * **Don't Do This:** Allow slow tests to accumulate. Address performance bottlenecks promptly. **Why:** Fast tests encourage frequent testing and faster feedback loops. ## 2. Unit Testing tRPC Procedures ### 2.1. Purpose of Unit Tests Unit tests verify the logic within individual tRPC procedures in isolation. They focus on the specific functionality of the procedure, independent of external dependencies like databases, APIs, or front-end components. ### 2.2. Key Aspects to Unit Test * **Input Validation:** Verify that the procedure handles invalid inputs correctly, throwing appropriate errors. * **Business Logic:** Test the core logic of the procedure, ensuring that it performs the correct calculations and data transformations. * **Output:** Assert that the procedure returns the expected output for various inputs. * **Error Handling:** Check that the procedure handles errors gracefully and returns informative error messages. ### 2.3. Tools and Libraries Use testing frameworks like Jest, Mocha, or Vitest for writing unit tests. Mocking libraries like "jest-mock", "sinon", or "vitest" are helpful for isolating tRPC procedures. ### 2.4. Example: Unit Testing a Simple tRPC Procedure """typescript // src/server/routers/example.ts import { z } from "zod"; import { publicProcedure, router } from "../trpc"; export const exampleRouter = router({ hello: publicProcedure .input(z.object({ text: z.string() })) .query(({ input }) => { return { greeting: "Hello ${input.text}", }; }), complexProcedure: publicProcedure .input( z.object({ id: z.number(), name: z.string(), }) ) .query(({ input }) => { //Simulate a database query (replace with actual logic) const data = { id: input.id, name: input.name, status: "active" }; return data; }), }); // src/server/routers/example.test.ts import { exampleRouter } from "./example"; import { createMockContext } from "../../test/mockContext"; // Assumed mock context function describe("exampleRouter", () => { it("should return a greeting with the provided text", async () => { const mockCtx = createMockContext(); // Create a mock context const caller = exampleRouter.createCaller(mockCtx); const result = await caller.hello({ text: "World" }); expect(result).toEqual({ greeting: "Hello World" }); }); it("should return data object with the correct input values", async () => { const mockCtx = createMockContext(); const caller = exampleRouter.createCaller(mockCtx); const input = { id: 123, name: "Test Name" }; const result = await caller.complexProcedure(input); expect(result).toEqual({ id: 123, name: "Test Name", status: "active" }); }); it("should successfully call complexProcedure with valid input", async () => { const mockCtx = createMockContext(); // Assuming you have a mock context function const caller = exampleRouter.createCaller(mockCtx); const input = { id: 1, name: "TestUser" }; const result = await caller.complexProcedure(input); expect(result).toBeDefined(); expect(result.id).toBe(input.id); expect(result.name).toBe(input.name); }); it("should handle invalid input for hello procedure", async () => { const mockCtx = createMockContext(); const caller = exampleRouter.createCaller(mockCtx); await expect(caller.hello({ text: 123 as any })).rejects.toThrowError(); // or specific Zod error }); }); // src/test/mockContext.ts (Example mock context, adapt as needed) import { inferAsyncReturnType } from "@trpc/server"; import { mockDeep, DeepMockProxy } from "jest-mock"; export type MockContext = { // Add any context dependencies needed for your procedures here }; export type Context = inferAsyncReturnType<typeof createMockContext>; export const createMockContext = (): MockContext => { return { // Mock any dependencies }; }; """ **Explanation:** * The test file imports the "exampleRouter" and the "createMockContext" utility. * "createContext" (or "createMockContext" in this example) needs to be mocked. This mock allows testing trpc procedures in isolation * The tests use "exampleRouter.createCaller(mockCtx)" to create a caller that mimics the tRPC server-side execution environment. This lets you directly call the procedure. * Each test case focuses on a specific aspect of the procedure's behavior. * Assertions use "expect" to verify the expected results. * For input validation, the "rejects.toThrowError()" is used to ensure invalid input throws an error, as defined by the Zod schema. ### 2.5. Common Anti-Patterns * **Testing Implementation Details:** Avoid testing internal implementation details of your tRPC procedures. Focus on testing the public API and its behavior. * **Over-Mocking:** Overusing mocks can make tests brittle and less reliable. Only mock external dependencies that are truly necessary to isolate the procedure. * **Ignoring Edge Cases:** Neglecting to test edge cases and boundary conditions can lead to subtle bugs in production. ### 2.6. Advanced Unit Testing Strategies * **Property-Based Testing:** Use property-based testing libraries like "fast-check" to automatically generate a wide range of inputs and verify that your tRPC procedures satisfy certain properties. * **Mutation Testing:** Use mutation testing tools like Stryker to assess the quality of your unit tests by introducing small changes (mutations) to your code and verifying that your tests detect these mutations. ## 3. Integration Testing tRPC Applications ### 3.1. Purpose of Integration Tests Integration tests verify the interaction between different parts of your tRPC application, such as procedures, databases, APIs, and middleware. Integration tests catch issues that may arise when these components are combined. ### 3.2. Key Aspects to Integration Test * **tRPC Procedure Interactions:** Test how different tRPC procedures interact with each other. * **Database Interactions:** Verify that tRPC procedures correctly read and write data to the database. * **External API Calls:** Test how tRPC procedures interact with external APIs and services. * **Middleware:** Ensure that middleware functions correctly intercept and modify requests or responses. * **Context:** Verify that the context object is correctly populated and passed to tRPC procedures. ### 3.3. Tools and Libraries * Use the same testing framework as your unit tests (Jest, Mocha, or Vitest). * Consider using a test database or a mocking library to isolate your integration tests from the production database. * Use tools like "supertest" or "node-fetch" to make HTTP requests to your tRPC server. ### 3.4. Example: Integration Testing with Supertest """typescript // src/server/index.ts (Simplified example) import { createHTTPServer } from "@trpc/server/adapters/standalone"; import { appRouter } from "./routers/_app"; import { createContext } from "./context"; const server = createHTTPServer({ router: appRouter, createContext, }); server.listen(3000); export type AppRouter = typeof appRouter; // src/server/routers/_app.ts import { router } from "../trpc"; import { exampleRouter } from "./example"; export const appRouter = router({ example: exampleRouter, }); // integration.test.ts import request from "supertest"; import {appRouter} from "./routers/_app"; import { createHTTPServer } from "@trpc/server/adapters/standalone"; import {createServer} from "@trpc/server/adapters/node-http" const testServer = createServer({ router: appRouter, createContext: () => ({}), // Mock context or real one for testing }); describe("tRPC API Integration Tests", () => { it("should call the hello procedure and return a greeting", async () => { const response = await request(testServer).get( "/example.hello?batch=0&input=%7B%22text%22%3A%22Integration%20Test%22%7D" ); expect(response.statusCode).toBe(200); expect(JSON.parse(response.text)).toEqual({ result: { data: { greeting: "Hello Integration Test" } } }); }); }); """ **Explanation:** * We import "request" from "supertest" to make HTTP requests to the tRPC server. * We start the tRPC server in a beforeAll hook to ensure it is running before the tests. * The test case uses "request(app)" to make a GET request to the "/api/trpc/hello" endpoint. * The request includes the input as a URL-encoded query parameter. * The assertions verify the response status code and the response body. * The tests need proper URL encoding for inputs. Consider using a utility function for this. ### 3.5. Common Anti-Patterns * **Relying on Real Data:** Avoid using real data in your integration tests. Use test data or mock data to ensure consistent and predictable results. * **Skipping Error Handling:** Neglecting to test error handling scenarios can lead to missed bugs. ### 3.6. Testing Middleware Testing middleware requires creating a mock tRPC context and verifying it’s correctly modified by the middleware. """typescript //Example Middleware import { t } from "../trpc"; const authMiddleware = t.middleware(async ({ ctx, next }) => { // Simulate auth check const user = { id: 1, name: "Test User" }; return next({ ctx: { ...ctx, user, }, }); }); export const protectedProcedure = t.procedure.use(authMiddleware); //Middleware Test import { protectedProcedure } from "./middleware"; import { initTRPC } from "@trpc/server"; const t = initTRPC.create(); describe("Middleware Tests", () => { it("should add user to context", async () => { const mockCtx = {}; const resolver = jest.fn(); // Mock resolver function const procedure = protectedProcedure.query(resolver); await procedure({ ctx: mockCtx, input: undefined }); expect(resolver).toHaveBeenCalled(); const contextPassedToResolver = resolver.mock.calls[0][0].ctx; expect(contextPassedToResolver.user).toBeDefined(); expect(contextPassedToResolver.user.id).toBe(1); }); }); """ ## 4. End-to-End (E2E) Testing tRPC Applications ### 4.1. Purpose of E2E Tests End-to-end tests simulate real user interactions with your tRPC application, verifying that the entire system works as expected from the user's perspective. This often involves testing the front-end as well. ### 4.2. Key Aspects to E2E Test * **User Flows:** Test common user flows, such as logging in, creating a new item, or submitting a form. * **Data Consistency:** Verify that data is consistent across the entire system. * **Error Handling:** Ensure that errors are handled gracefully and that users receive informative error messages. ### 4.3. Tools and Libraries * Use E2E testing frameworks like Cypress, Playwright, or Selenium. * Consider using a test database or a staging environment to isolate your E2E tests from the production environment. ### 4.4. Example: E2E Testing with Cypress (Requires a running tRPC and front-end application) """javascript // cypress/e2e/example.cy.js describe('tRPC Example', () => { it('Visits the app and displays a greeting', () => { cy.visit('http://localhost:3000'); // Replace with your app's URL cy.contains('Hello World'); // Assuming your front-end displays "Hello World" via tRPC }) it('Can submit a form and see the result', () => { cy.visit('http://localhost:3000'); // Replace with your app's URL cy.get('input[name="text"]').type('Cypress Test'); cy.get('button[type="submit"]').click(); cy.contains('Hello Cypress Test'); // Assuming the form sends data to a tRPC endpoint }) }) """ **Explanation:** * This example assumes you have a front-end application that interacts with your tRPC backend. * The script visits your front-end and interacts with the UI. * For testing tRPC calls Cypress intercepts network requests & mocks the responses. ### 4.5. Common Anti-Patterns * **Unstable Tests:** Ensure tests do not have random failures. * **Ignoring Error Messages:** Neglecting to assert user-facing error messages can mask critical problems. ### 4.6. Database State Management in E2E tests Resetting the database state between each test is crucial to ensure test reliability and isolation. ## 5. Tips for Effective tRPC Testing ### 5.1. Utilize "superjson" effectively. Ensure your tests handle "superjson" serialization / deserialization properly, especially when dealing with Dates or other complex types. ### 5.2. Handle Asynchronous Operations Correctly Use "async/await" or Promises to wait for asynchronous operations to complete before making assertions. ### 5.3. Mock the "createContext" function This allows you to isolate the tRPC procedures from external dependencies and inject mock context values for testing purposes. This is shown in more detail in sections 2.4 and 3.6 ### 5.4. Test Error Cases Always test error cases to ensure your procedures handle errors gracefully and return informative error messages. Use "try...catch" blocks or promise rejection handlers to catch errors and assert that they are handled correctly. ### 5.5. Use environment variables for configuration This allows you to easily switch between different environments (e.g., development, testing, production) without modifying your code. ### 5.6. Test batching functionality When your tRPC API uses batching, ensure your tests cover scenarios where multiple requests are batched together. ### 5.7 Define and use common test helpers Creating a module of helper functions to perform repetitive test operations (e.g., creating users, populating databases) keeps your tests DRY (Don't Repeat Yourself) and maintainable. By adhering to these testing methodologies standards, you can build robust and reliable tRPC applications with confidence. Remember to adapt these guidelines to your specific project requirements.