.cursorrules (deprecated)

1# T3 Stack — Cursor Rules
2# Comprehensive rules for T3 Stack (Next.js + tRPC + Prisma + NextAuth)
3 
4## Project Context
5You are working on a T3 Stack application — the full-stack TypeScript framework combining
6Next.js App Router, tRPC for type-safe APIs, Prisma for database access, and NextAuth.js
7for authentication. The codebase prioritizes end-to-end type safety, with types flowing
8from database schema through API layer to the frontend without manual type definitions.
9 
10## Tech Stack
11- Next.js 14+ (App Router)
12- tRPC v11 for type-safe API layer
13- Prisma ORM for database (PostgreSQL recommended)
14- NextAuth.js / Auth.js for authentication
15- Tailwind CSS for styling
16- TypeScript (strict mode — non-negotiable)
17- Zod for input validation
18- React Query (via tRPC) for server state
19 
20## Coding Style
21 
22### Naming Conventions
23- tRPC routers: camelCase (e.g., `userRouter`, `postRouter`)
24- tRPC procedures: camelCase verbs (e.g., `getById`, `create`, `updateStatus`)
25- Prisma models: PascalCase singular (e.g., `User`, `Post`, `Comment`)
26- Components: PascalCase (e.g., `PostCard`, `UserAvatar`)
27- Server utilities: camelCase in `src/server/`
28- Client hooks: `use` prefix (e.g., `useCreatePost`)
29 
30### Project Structure
31```
32src/
33  app/
34    (auth)/
35      sign-in/page.tsx
36    (dashboard)/
37      layout.tsx
38      page.tsx
39      posts/
40        [id]/page.tsx
41    api/
42      trpc/[trpc]/route.ts    # tRPC HTTP handler
43      auth/[...nextauth]/route.ts
44    layout.tsx
45    page.tsx
46  server/
47    api/
48      root.ts               # Root tRPC router
49      trpc.ts               # tRPC initialization, context, middleware
50      routers/
51        user.ts
52        post.ts
53    auth.ts                  # NextAuth configuration
54    db.ts                    # Prisma client singleton
55  trpc/
56    react.tsx                # tRPC React client setup
57    server.ts                # tRPC server caller
58  components/
59    ui/                      # Shared UI components
60    posts/                   # Feature-specific components
61  lib/
62    utils.ts
63    validators.ts            # Shared Zod schemas
64prisma/
65  schema.prisma
66```
67 
68## tRPC Patterns
69 
70### Router Definition
71```ts
72// server/api/routers/post.ts
73import { z } from "zod";
74import { createTRPCRouter, protectedProcedure, publicProcedure } from "../trpc";
75import { TRPCError } from "@trpc/server";
76 
77export const postRouter = createTRPCRouter({
78  getAll: publicProcedure
79    .input(z.object({
80      limit: z.number().min(1).max(100).default(20),
81      cursor: z.string().nullish(),
82    }))
83    .query(async ({ ctx, input }) => {
84      const posts = await ctx.db.post.findMany({
85        take: input.limit + 1,
86        cursor: input.cursor ? { id: input.cursor } : undefined,
87        orderBy: { createdAt: "desc" },
88        include: { author: { select: { name: true, image: true } } },
89      });
90      let nextCursor: string | undefined;
91      if (posts.length > input.limit) {
92        nextCursor = posts.pop()!.id;
93      }
94      return { posts, nextCursor };
95    }),
96 
97  create: protectedProcedure
98    .input(z.object({
99      title: z.string().min(1).max(200),
100      content: z.string().min(1),
101    }))
102    .mutation(async ({ ctx, input }) => {
103      return ctx.db.post.create({
104        data: { ...input, authorId: ctx.session.user.id },
105      });
106    }),
107 
108  delete: protectedProcedure
109    .input(z.object({ id: z.string() }))
110    .mutation(async ({ ctx, input }) => {
111      const post = await ctx.db.post.findUnique({ where: { id: input.id } });
112      if (!post) throw new TRPCError({ code: "NOT_FOUND" });
113      if (post.authorId !== ctx.session.user.id) {
114        throw new TRPCError({ code: "FORBIDDEN" });
115      }
116      return ctx.db.post.delete({ where: { id: input.id } });
117    }),
118});
119```
120 
121### tRPC Context and Middleware
122```ts
123// server/api/trpc.ts
124import { initTRPC, TRPCError } from "@trpc/server";
125import superjson from "superjson";
126import { getServerSession } from "next-auth";
127import { authOptions } from "../auth";
128import { db } from "../db";
129 
130const createTRPCContext = async (opts: { headers: Headers }) => {
131  const session = await getServerSession(authOptions);
132  return { db, session, ...opts };
133};
134 
135const t = initTRPC.context<typeof createTRPCContext>().create({
136  transformer: superjson,
137  errorFormatter({ shape, error }) {
138    return { ...shape, data: { ...shape.data, zodError: error.cause instanceof ZodError ? error.cause.flatten() : null } };
139  },
140});
141 
142export const createTRPCRouter = t.router;
143export const publicProcedure = t.procedure;
144export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
145  if (!ctx.session?.user) throw new TRPCError({ code: "UNAUTHORIZED" });
146  return next({ ctx: { session: { ...ctx.session, user: ctx.session.user } } });
147});
148```
149 
150### Client-Side Usage
151```tsx
152"use client";
153import { api } from "~/trpc/react";
154 
155export function PostList() {
156  const { data, fetchNextPage, hasNextPage, isLoading } = api.post.getAll.useInfiniteQuery(
157    { limit: 20 },
158    { getNextPageParam: (lastPage) => lastPage.nextCursor },
159  );
160 
161  const utils = api.useUtils();
162  const createPost = api.post.create.useMutation({
163    onSuccess: () => {
164      utils.post.getAll.invalidate(); // Refetch after mutation
165    },
166  });
167 
168  // ...
169}
170```
171 
172### Server-Side Calling
173```tsx
174// In a Server Component — call tRPC directly without HTTP
175import { api } from "~/trpc/server";
176 
177export default async function PostPage({ params }: { params: { id: string } }) {
178  const post = await api.post.getById({ id: params.id });
179  return <PostDetail post={post} />;
180}
181```
182 
183## Prisma Patterns
184- Define clear relations with `@relation` and explicit foreign keys
185- Use `select` or `include` to control returned fields — never return everything
186- Use transactions for multi-table mutations: `db.$transaction([])`
187- Create seed data in `prisma/seed.ts`
188- Run migrations with `npx prisma migrate dev --name descriptive_name`
189- Use `@map` and `@@map` for custom table/column names matching SQL conventions
190- Add indexes on frequently queried/filtered columns
191 
192## Authentication
193- Use NextAuth.js with the Prisma adapter
194- Access session in tRPC context — never pass user info from the client
195- Use `protectedProcedure` for all authenticated endpoints
196- Check resource ownership in procedures (not just authentication)
197- Use middleware for role-based access control
198 
199## Error Handling
200- Use `TRPCError` with appropriate codes: `NOT_FOUND`, `UNAUTHORIZED`, `FORBIDDEN`, `BAD_REQUEST`
201- Validate all inputs with Zod schemas — tRPC integrates natively
202- Handle Prisma errors (unique constraint, not found) and map to TRPCError
203- Use React error boundaries for client-side error display
204- Format Zod errors in the tRPC error formatter for client consumption
205 
206## Testing
207- Test tRPC procedures by creating a test caller with mocked context
208- Test Prisma queries against a test database (or use prismock)
209- Use Playwright for E2E tests
210- Test auth flows with mocked sessions
211 
212## Performance Guidelines
213- Use cursor-based pagination (not offset) for large datasets
214- Prefetch data in Server Components using the server-side tRPC caller
215- Use React Query's `staleTime` to reduce unnecessary refetches
216- Use `select` in Prisma to fetch only needed fields
217- Implement optimistic updates for mutations that affect UI immediately
218- Use `Suspense` boundaries for streaming server-rendered content
219 
220## Common Pitfalls
221- Importing server code in client components (breaks the build)
222- Not invalidating queries after mutations (stale UI)
223- Using offset pagination for large tables (slow on large offsets)
224- Returning full Prisma objects with sensitive fields to the client
225- Not checking resource ownership — just checking authentication is not enough
226- Forgetting `superjson` transformer (dates, Maps, Sets won't serialize correctly)
227- Not wrapping client providers properly in the root layout
228- Using `getServerSession` outside of RSC/route handlers (wrong context)
229