Cursor AI — Advanced Tips and Tricks for 2026

# .cursorrules — Advanced example for a TypeScript + Node.js + PostgreSQL project
 
## Architecture
- Express.js REST API with TypeScript
- PostgreSQL via Prisma ORM
- Redis for session management and caching
- Bull for background job queues
- Jest for testing
 
## File Structure
- src/routes/ — Express route handlers (thin — validation only)
- src/services/ — Business logic layer
- src/repositories/ — Database access layer (Prisma calls only here)
- src/workers/ — Bull job processors
- src/types/ — Shared TypeScript types and interfaces
 
## TypeScript Standards
- Strict mode enabled (tsconfig strict: true)
- No 'any' type except in rare, documented exceptions
- All functions must have explicit return types
- Use 'z' (zod) for runtime validation of external inputs
- Prefer 'type' over 'interface' except for class implementations
 
## Error Handling
- All route handlers are wrapped in asyncHandler middleware
- Services throw custom error classes: ValidationError, NotFoundError, ConflictError
- Never return raw Prisma errors to the client
 
## Testing
- Unit tests for services and repositories (mock Prisma with jest-mock-extended)
- Integration tests for routes using supertest
- Test files named *.test.ts, colocated with source files
 
## Security Requirements
- All user input sanitized through zod schemas before use
- SQL queries only via Prisma (no raw SQL without explicit security review comment)
- Passwords hashed with bcrypt, minimum cost factor 12
- JWT tokens expire in 15 minutes; refresh tokens in 7 days
 
## Do Not
- Write business logic in route handlers
- Call Prisma directly from routes
- Use var or function declarations (use const and arrow functions)
- Catch errors without either rethrowing or logging

Step 1 Composer: "Add a UserPreferences model to schema.prisma with
fields: userId (FK to User), theme (enum: light/dark), emailNotifications (boolean)"
 
[Review and accept Step 1]
 
Step 2 Composer: "Generate the Prisma migration for the UserPreferences model
and create a userPreferencesRepository.ts in src/repositories/"
 
[Review and accept Step 2]
 
Step 3 Composer: "Create a userPreferencesService.ts that wraps the repository.
Add getPreferences(userId) and updatePreferences(userId, data) methods.
Follow the service pattern in src/services/userService.ts"
 
[Review and accept Step 3]
 
Step 4 Composer: "Add routes for GET and PATCH /users/:id/preferences to routes/users.ts.
Include zod validation. Add jest tests."

Less effective:
"Update the authentication system"
(No reference to existing files)
 
More effective:
"Looking at @file:src/services/authService.ts and @file:src/types/auth.ts,
add token refresh functionality. Follow the same pattern as the login function.
Update @file:src/routes/auth.ts to add the refresh endpoint."
 
Most effective (explicit file references + constraints):
"Referencing:
- @file:src/services/authService.ts (existing auth logic)
- @file:src/repositories/userRepository.ts (user data access)
- @file:src/middleware/auth.ts (current JWT validation)
 
Add refresh token logic:
1. generateRefreshToken() stores token hash in Redis with 7-day TTL
2. POST /auth/refresh validates refresh token, returns new access + refresh tokens
3. POST /auth/logout invalidates the refresh token in Redis
4. Do not modify the existing login flow"

Effective debugging prompt structure:
 
@file:src/services/paymentService.ts
 
I'm getting this error when calling chargeUser():

 
This happens intermittently, approximately 1 in 100 calls.
The user definitely exists in the database (confirmed via logging).
 
What's the most likely cause and how do I fix it?

@web "How do I configure connection pooling in Prisma 5.x?
Show the exact prisma.schema configuration."
 
@web "What changed in Next.js 15 app router that would cause
this hydration error: [error message]?"

Chat prompt:
"For this session only, act as a security auditor.
Review each piece of code I share for OWASP Top 10 vulnerabilities.
Be conservative — flag potential issues even if not certain.
 
Now review: @file:src/routes/users.ts"

Instead of: "@codebase how does caching work here?"
 
Use: "@codebase in the context of Redis and session management,
how does the caching layer work? Focus on src/middleware/ and src/utils/"
 
Or use file glob patterns in Composer:
"Looking at all files matching src/services/*.ts,
identify which ones are missing error handling for database connection failures."

TDD pattern with Cursor:
 
1. Write the test first (manually or via Composer):
   "Write a failing Jest test for a createOrder service function that:
   - Takes userId and cartItems
   - Validates stock availability
   - Creates the order in the database
   - Reduces inventory
   Cover: success case, out of stock, invalid userId"
 
2. Run the tests to confirm they fail:
   npm test -- --testPathPattern=orderService
 
3. Use Composer to implement:
   "Implement the createOrder function in src/services/orderService.ts
   to pass these tests: @file:src/services/orderService.test.ts"
 
4. Run tests again to confirm they pass