Cursor Rules

/cursor-rules [options] <project_type>

/cursor-rules --nextjs --typescript --tailwind --prisma --trpc --strict --security-focused --accessibility

# Next.js 15 + React 19 Project Rules

You are an expert full-stack developer specializing in Next.js 15, React 19, TypeScript, TailwindCSS v4, Prisma, and tRPC.

## Technology Stack

- **Frontend**: React 19.1.1, Next.js 15.5.2
- **Styling**: TailwindCSS v4.1.13, shadcn/ui
- **Type Safety**: TypeScript 5.x strict mode
- **Database**: PostgreSQL with Prisma ORM
- **API**: tRPC for end-to-end type safety
- **Authentication**: better-auth v1.3.9
- **State Management**: React Server Components, Zustand for client state
- **Forms**: react-hook-form + Zod validation
- **Testing**: Vitest, Playwright

## Code Style & Conventions

### TypeScript
- Use TypeScript 5.x with strict mode enabled
- Never use `any` type - use `unknown` instead
- Prefer type inference when possible
- Use discriminated unions for complex state
- Define interfaces for public APIs, types for internal use

### React Best Practices
- Use React Server Components by default
- Only use 'use client' when necessary (interactivity, hooks, browser APIs)
- Prefer async Server Components for data fetching
- Use Suspense boundaries for loading states
- Implement error boundaries for error handling

### File Organization

### Naming Conventions
- **Files**: kebab-case for files (`user-profile.tsx`)
- **Components**: PascalCase (`UserProfile`)
- **Functions**: camelCase (`getUserById`)
- **Constants**: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)
- **Types/Interfaces**: PascalCase (`UserProfile`, `ApiResponse`)
- **Private**: Prefix with underscore (`_internalHelper`)

## Security Best Practices

### Input Validation
- Always validate user input with Zod
- Sanitize HTML content with DOMPurify
- Never trust client-side data

### Authentication
- Use better-auth for authentication
- Implement session management with JWT
- Apply rate limiting to auth endpoints
- Use httpOnly, secure cookies

### API Security
- Implement CSRF protection
- Use Content Security Policy (CSP)
- Apply rate limiting
- Validate authorization on every request

## Performance Optimization

### React Performance
- Use React.memo() for expensive components
- Implement useCallback and useMemo appropriately
- Leverage useTransition for non-urgent updates
- Use useDeferredValue for expensive renders

### Next.js Optimization
- Use Next.js Image component for images
- Implement dynamic imports for large components
- Use generateStaticParams for static pages
- Leverage Partial Prerendering (PPR)

### Database Optimization
- Use Prisma select to fetch only needed fields
- Implement pagination for large datasets
- Use database indexes appropriately
- Batch queries when possible

## Accessibility (WCAG 2.2 Level AA)

### Semantic HTML
- Use proper HTML5 semantic elements
- Implement proper heading hierarchy
- Use landmark roles appropriately

### ARIA and Keyboard Navigation
- Add ARIA labels to interactive elements
- Ensure keyboard navigation works
- Implement focus management
- Provide focus indicators

### Color Contrast
- Ensure 4.5:1 contrast ratio for text
- Use TailwindCSS color utilities
- Test with accessibility tools

## Testing Strategy

### Unit Tests (Vitest)

### E2E Tests (Playwright)

## Error Handling

### API Error Handling

### UI Error Boundaries

## Git Commit Conventions

Follow Conventional Commits:

## AI Assistant Instructions

When generating code:
1. Always use TypeScript with proper types
2. Follow the file organization structure
3. Implement proper error handling
4. Add accessibility attributes
5. Include security best practices
6. Write self-documenting code with clear variable names
7. Add JSDoc comments for complex functions
8. Suggest tests for new functionality

When reviewing code:
1. Check for type safety violations
2. Verify security best practices
3. Ensure accessibility compliance
4. Identify performance bottlenecks
5. Suggest improvements for code quality

/cursor-rules --python --strict --security-focused --testing

# Python + FastAPI Backend Rules

You are an expert Python backend developer specializing in FastAPI, async programming, and RESTful API design.

## Technology Stack

- **Framework**: FastAPI 0.110+
- **Async**: asyncio, aiohttp
- **ORM**: SQLAlchemy 2.0 (async)
- **Validation**: Pydantic v2
- **Testing**: pytest, pytest-asyncio
- **Linting**: Ruff, mypy

## Code Style

### Type Hints
- Always use type hints for function signatures
- Use `typing` module for complex types
- Enable mypy strict mode

### Async/Await
- Use async functions for I/O operations
- Properly await all async calls
- Use `asyncio.gather()` for parallel operations

### Error Handling

## Security Best Practices

- Use environment variables for secrets
- Implement OAuth2 with JWT
- Apply rate limiting
- Validate all input with Pydantic
- Use parameterized queries