.cursorrules (deprecated)

1# Full-Stack Next.js + Prisma + PostgreSQL + Tailwind — Cursor Rules
2# End-to-end patterns for modern full-stack Next.js applications
3 
4# Project Context
5You are building a full-stack web application with Next.js 14+ (App Router), Prisma ORM with
6PostgreSQL, and Tailwind CSS. The project uses TypeScript throughout, Server Components for data
7fetching, Server Actions for mutations, and follows full-stack best practices.
8 
9# Project Structure
10```
11src/
12  app/
13    (auth)/               # Auth route group (login, register)
14    (dashboard)/          # Dashboard route group
15    api/                  # API routes (webhooks, external integrations only)
16    layout.tsx
17    page.tsx
18  actions/                # Server Actions
19    user.actions.ts
20    project.actions.ts
21  components/
22    ui/                   # Generic UI components (Button, Input, Card)
23    forms/                # Form components with validation
24    layouts/              # Layout components
25  lib/
26    db.ts                 # Prisma client singleton
27    auth.ts               # Auth utilities (NextAuth or custom)
28    validations/          # Zod schemas
29    utils.ts              # Shared utilities
30  types/                  # TypeScript types (non-Prisma)
31prisma/
32  schema.prisma           # Prisma schema
33  migrations/             # Generated migrations
34  seed.ts                 # Database seed script
35```
36 
37# Prisma Schema Patterns
38- Use meaningful model names (singular, PascalCase): `User`, `Project`, `Comment`.
39- Always define `createdAt` and `updatedAt` on every model:
40```prisma
41  model User {
42    id        String   @id @default(cuid())
43    email     String   @unique
44    name      String?
45    role      Role     @default(USER)
46    posts     Post[]
47    createdAt DateTime @default(now())
48    updatedAt DateTime @updatedAt
49 
50    @@index([email])
51    @@map("users")
52  }
53```
54- Use `cuid()` or `uuid()` for IDs — not auto-increment integers (security + distributed-friendly).
55- Add `@@index` on fields used in WHERE clauses and foreign keys.
56- Use enums for fixed sets of values: `enum Role { USER ADMIN MODERATOR }`.
57- Use `@@map("table_name")` to control database table names (plural, snake_case).
58- Use `@map("column_name")` for column name mapping when conventions differ.
59 
60# Prisma Client Singleton
61- Create a single Prisma client instance to avoid connection pool exhaustion:
62```typescript
63  // lib/db.ts
64  import { PrismaClient } from '@prisma/client';
65 
66  const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
67  export const prisma = globalForPrisma.prisma ?? new PrismaClient();
68  if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
69```
70- Import from `@/lib/db` everywhere — never create new `PrismaClient()` instances.
71 
72# Data Fetching in Server Components
73- Fetch data directly in Server Components using Prisma:
74```typescript
75  // app/dashboard/page.tsx
76  import { prisma } from '@/lib/db';
77 
78  export default async function DashboardPage() {
79    const projects = await prisma.project.findMany({
80      where: { userId: session.user.id },
81      include: { tasks: { where: { completed: false } } },
82      orderBy: { updatedAt: 'desc' },
83    });
84    return <ProjectList projects={projects} />;
85  }
86```
87- Use `select` to fetch only needed fields (reduces data transfer).
88- Use `include` sparingly — only load relations you actually render.
89- DON'T: Create API routes to fetch data for your own pages — use Server Components.
90- DON'T: Use Prisma on the client — it's server-only.
91 
92# Server Actions for Mutations
93- Define actions in dedicated files with `"use server"` directive:
94```typescript
95  // actions/project.actions.ts
96  "use server";
97  import { z } from 'zod';
98  import { prisma } from '@/lib/db';
99  import { revalidatePath } from 'next/cache';
100 
101  const createProjectSchema = z.object({
102    name: z.string().min(1).max(100),
103    description: z.string().max(500).optional(),
104  });
105 
106  export async function createProject(formData: FormData) {
107    const session = await getSession();
108    if (!session) throw new Error('Unauthorized');
109 
110    const parsed = createProjectSchema.safeParse({
111      name: formData.get('name'),
112      description: formData.get('description'),
113    });
114    if (!parsed.success) return { error: parsed.error.flatten() };
115 
116    const project = await prisma.project.create({
117      data: { ...parsed.data, userId: session.user.id },
118    });
119 
120    revalidatePath('/dashboard');
121    return { data: project };
122  }
123```
124- Always validate input with zod before database operations.
125- Always verify authentication and authorization in every action.
126- Use `revalidatePath()` after mutations to refresh cached data.
127- Return structured results, not throw errors (for form state handling).
128 
129# Tailwind CSS Patterns
130- Use Tailwind utility classes directly in JSX.
131- Extract repeated patterns into components, not CSS classes:
132```typescript
133  // DO: Create a reusable component
134  function Card({ children }: { children: React.ReactNode }) {
135    return <div className="rounded-lg border bg-white p-6 shadow-sm">{children}</div>;
136  }
137  // DON'T: @apply in CSS (defeats the purpose of utility-first)
138```
139- Use `cn()` utility (clsx + tailwind-merge) for conditional classes:
140```typescript
141  import { clsx, type ClassValue } from 'clsx';
142  import { twMerge } from 'tailwind-merge';
143  export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }
144```
145- Use Tailwind's `@screen` breakpoints: `sm:`, `md:`, `lg:`, `xl:`, `2xl:`.
146- Design mobile-first: base styles for mobile, add breakpoint prefixes for larger screens.
147 
148# Authentication Pattern
149- Use NextAuth.js (Auth.js) or implement custom auth with JWT.
150- Protect Server Components by checking session in the component:
151```typescript
152  const session = await getServerSession(authOptions);
153  if (!session) redirect('/login');
154```
155- Protect Server Actions by verifying session at the start of every action.
156- Store session data in a secure HttpOnly cookie.
157- Use middleware.ts for route-level protection (redirect unauthenticated users).
158 
159# Form Handling
160- Use Server Actions with progressive enhancement:
161```tsx
162  <form action={createProject}>
163    <input name="name" required />
164    <SubmitButton />
165  </form>
166```
167- Use `useFormState` and `useFormStatus` for client-side form state and pending UI.
168- Show validation errors returned from Server Actions.
169- Use optimistic updates with `useOptimistic` for better UX.
170 
171# Database Migrations
172- Run `npx prisma migrate dev --name descriptive-name` for development migrations.
173- Run `npx prisma migrate deploy` in production (CI/CD).
174- Never edit existing migrations — create new ones.
175- Use `prisma db seed` for development data. Configure in package.json.
176 
177# Performance
178- Use Prisma's `select` to fetch only needed fields.
179- Add database indexes for common query patterns.
180- Use Next.js caching: `unstable_cache()` for database queries.
181- Implement pagination for list queries — never load unbounded result sets.
182- Use `<Suspense>` with loading.tsx for streaming SSR.
183- Use `loading.tsx` at route segments for instant loading states.
184 
185# Security
186- Validate ALL input with zod at the Server Action boundary.
187- Use parameterized queries (Prisma does this by default — never use `$queryRawUnsafe`).
188- Implement rate limiting on sensitive actions (login, registration).
189- Sanitize user-generated content before rendering.
190- Use CSRF protection (Next.js Server Actions handle this automatically).
191 
192# Testing
193- Use Vitest for unit tests (faster than Jest with TypeScript).
194- Test Server Actions by calling them directly with mock FormData.
195- Use Playwright for E2E tests of critical flows.
196- Use a test database with `prisma migrate reset` between test suites.
197- Mock Prisma client for unit tests using `vitest-mock-extended`.
198 
199# Common Mistakes to Avoid
200- DON'T: Import Prisma client in Client Components — it only works server-side.
201- DON'T: Create API routes for your own data fetching — use Server Components.
202- DON'T: Skip input validation in Server Actions — forms can be submitted with any data.
203- DON'T: Use `findFirst` without `where` — it returns a random record.
204- DON'T: Forget `revalidatePath` after mutations — the UI won't update.
205- DON'T: Store Prisma-generated types in your own types file — import from `@prisma/client`.
206