.cursorrules (deprecated)

1# MERN Stack — Cursor Rules
2# Comprehensive rules for MongoDB + Express + React + Node.js applications
3 
4## Project Context
5You are working on a MERN stack application: MongoDB for the database, Express.js for
6the API server, React for the frontend, and Node.js as the runtime. The project may be
7a monorepo or split into separate client/server directories. The codebase uses modern
8JavaScript/TypeScript and follows REST API conventions.
9 
10## Tech Stack
11- MongoDB with Mongoose ODM (or MongoDB Node driver)
12- Express.js 4.x for API server
13- React 18+ with TypeScript
14- Node.js 20+ LTS
15- Vite for React client bundling
16- JWT for authentication
17- Zod for API validation
18- React Query for server state management
19 
20## Coding Style
21 
22### Naming Conventions
23- MongoDB collections: plural lowercase (e.g., `users`, `orders`, `orderItems`)
24- Mongoose models: PascalCase singular (e.g., `User`, `Order`)
25- Express routes: kebab-case URLs (e.g., `/api/order-items`)
26- React components: PascalCase (e.g., `OrderList`, `UserProfile`)
27- API endpoints: RESTful nouns (e.g., `GET /api/users`, `POST /api/orders`)
28- Environment variables: UPPER_SNAKE_CASE with app prefix (e.g., `APP_MONGO_URI`)
29 
30### Project Structure (Monorepo)
31```
32packages/
33  client/                 # React frontend
34    src/
35      components/         # Reusable UI components
36      features/           # Feature modules (auth, dashboard, orders)
37        auth/
38          components/
39          hooks/
40          api.ts          # API calls for this feature
41          types.ts
42      hooks/              # Shared hooks
43      lib/                # Utilities, API client setup
44      types/              # Shared types
45  server/                 # Express backend
46    src/
47      config/             # Database, env config
48        db.ts
49        env.ts
50      controllers/        # Route handlers
51      middleware/          # Auth, validation, error handling
52      models/             # Mongoose models
53      routes/             # Route definitions
54      services/           # Business logic
55      utils/              # Utilities
56      validators/         # Zod schemas
57      app.ts
58      server.ts
59  shared/                 # Shared types/utilities (if monorepo)
60    types/
61```
62 
63## MongoDB / Mongoose Patterns
64 
65### Model Definition
66```ts
67import mongoose, { Schema, Document } from 'mongoose';
68 
69export interface IUser extends Document {
70  email: string;
71  name: string;
72  passwordHash: string;
73  role: 'user' | 'admin';
74  createdAt: Date;
75  updatedAt: Date;
76}
77 
78const userSchema = new Schema<IUser>(
79  {
80    email: {
81      type: String,
82      required: true,
83      unique: true,
84      lowercase: true,
85      trim: true,
86      index: true,
87    },
88    name: { type: String, required: true, trim: true, maxlength: 100 },
89    passwordHash: { type: String, required: true, select: false },
90    role: { type: String, enum: ['user', 'admin'], default: 'user' },
91  },
92  {
93    timestamps: true,
94    toJSON: {
95      transform(doc, ret) {
96        ret.id = ret._id;
97        delete ret._id;
98        delete ret.__v;
99        delete ret.passwordHash;
100      },
101    },
102  },
103);
104 
105userSchema.index({ email: 1 });
106userSchema.index({ createdAt: -1 });
107 
108export const User = mongoose.model<IUser>('User', userSchema);
109```
110 
111### Query Patterns
112```ts
113// Use lean() for read-only queries (returns plain objects, ~5x faster)
114const users = await User.find({ role: 'user' }).lean().limit(20).skip(0);
115 
116// Use select() to limit returned fields
117const user = await User.findById(id).select('name email role');
118 
119// Use populate() sparingly — prefer denormalization for read-heavy data
120const order = await Order.findById(id)
121  .populate('user', 'name email')
122  .populate('items.product', 'name price');
123 
124// Aggregation for complex queries
125const stats = await Order.aggregate([
126  { $match: { status: 'completed', createdAt: { $gte: startDate } } },
127  { $group: { _id: '$user', totalSpent: { $sum: '$total' }, orderCount: { $sum: 1 } } },
128  { $sort: { totalSpent: -1 } },
129  { $limit: 10 },
130]);
131```
132 
133### Model Rules
134- Always define indexes for fields used in queries and sorts
135- Use `select: false` on sensitive fields (passwords, tokens)
136- Use `toJSON` transform to clean up response objects
137- Use `lean()` on read-only queries for performance
138- Validate at both the schema level and the API validation layer
139- Use transactions for multi-document operations: `session.withTransaction()`
140- Avoid deeply nested subdocuments — use references for entities that grow
141 
142## Express API Patterns
143 
144### Controller Pattern
145```ts
146export const orderController = {
147  async getAll(req: Request, res: Response, next: NextFunction) {
148    try {
149      const { page = 1, limit = 20, status } = req.query;
150      const filter: FilterQuery<IOrder> = { user: req.user.id };
151      if (status) filter.status = status;
152 
153      const [orders, total] = await Promise.all([
154        Order.find(filter).lean().sort('-createdAt').skip((+page - 1) * +limit).limit(+limit),
155        Order.countDocuments(filter),
156      ]);
157 
158      res.json({
159        data: orders,
160        meta: { page: +page, limit: +limit, total, pages: Math.ceil(total / +limit) },
161      });
162    } catch (error) {
163      next(error);
164    }
165  },
166};
167```
168 
169### API Validation Middleware
170```ts
171import { z } from 'zod';
172 
173const createOrderSchema = z.object({
174  body: z.object({
175    items: z.array(z.object({
176      product: z.string().regex(/^[a-f\d]{24}$/i, 'Invalid product ID'),
177      quantity: z.number().int().positive().max(100),
178    })).min(1, 'At least one item required'),
179    shippingAddress: z.object({
180      street: z.string().min(1),
181      city: z.string().min(1),
182      zip: z.string().min(1),
183    }),
184  }),
185});
186 
187function validate(schema: z.ZodSchema) {
188  return (req: Request, res: Response, next: NextFunction) => {
189    const result = schema.safeParse({ body: req.body, query: req.query, params: req.params });
190    if (!result.success) {
191      return res.status(400).json({ errors: result.error.flatten().fieldErrors });
192    }
193    next();
194  };
195}
196```
197 
198## React Frontend Patterns
199 
200### API Layer with React Query
201```ts
202// features/orders/api.ts
203import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
204import { apiClient } from '../../lib/api-client';
205 
206export function useOrders(page = 1) {
207  return useQuery({
208    queryKey: ['orders', page],
209    queryFn: () => apiClient.get(`/api/orders?page=${page}`).then(r => r.data),
210  });
211}
212 
213export function useCreateOrder() {
214  const queryClient = useQueryClient();
215  return useMutation({
216    mutationFn: (data: CreateOrderInput) => apiClient.post('/api/orders', data),
217    onSuccess: () => {
218      queryClient.invalidateQueries({ queryKey: ['orders'] });
219    },
220  });
221}
222```
223 
224### API Client Setup
225```ts
226// lib/api-client.ts
227import axios from 'axios';
228 
229export const apiClient = axios.create({
230  baseURL: import.meta.env.VITE_API_URL || 'http://localhost:5000',
231});
232 
233apiClient.interceptors.request.use((config) => {
234  const token = localStorage.getItem('token');
235  if (token) config.headers.Authorization = `Bearer ${token}`;
236  return config;
237});
238 
239apiClient.interceptors.response.use(
240  (response) => response,
241  (error) => {
242    if (error.response?.status === 401) {
243      localStorage.removeItem('token');
244      window.location.href = '/login';
245    }
246    return Promise.reject(error);
247  },
248);
249```
250 
251## Error Handling
252- Centralized Express error handler as the last middleware
253- Mongoose validation errors mapped to 400 responses
254- Cast errors (invalid ObjectId) mapped to 404
255- Duplicate key errors mapped to 409 Conflict
256- React error boundaries for component-level errors
257- React Query's `onError` for API error handling in the UI
258 
259## Security
260- Validate all API inputs with Zod (never trust the client)
261- Use `helmet` for secure HTTP headers
262- Use CORS with explicit allowed origins
263- Hash passwords with bcrypt (cost factor 12)
264- Validate ObjectIds before database queries
265- Sanitize user input to prevent NoSQL injection (`mongo-sanitize`)
266- Rate limit authentication endpoints
267- Store JWT secret in environment variables, use short expiry
268 
269## Testing
270- Use Jest or Vitest for unit and integration tests
271- Use `mongodb-memory-server` for database tests without external MongoDB
272- Test API endpoints with supertest
273- Test React components with React Testing Library
274- Test hooks with `renderHook` from React Testing Library
275 
276## Performance Guidelines
277- Use MongoDB indexes — compound indexes for multi-field queries
278- Use `lean()` on all read-only Mongoose queries
279- Implement pagination on all list endpoints
280- Use Redis for caching frequently accessed data
281- Compress responses with `compression` middleware
282- Use React Query's `staleTime` to reduce API calls
283- Lazy-load React routes and heavy components
284 
285## Common Pitfalls
286- Not handling MongoDB connection errors at startup
287- Using `findOne` without `lean()` when you don't need a Mongoose document
288- Not indexing fields used in `find()`, `sort()`, or `aggregate()`
289- N+1 queries from looping with `findById` — use `find({ _id: { $in: ids } })`
290- Not validating ObjectId format before passing to Mongoose (causes CastError)
291- Storing JWT tokens in localStorage without considering XSS (consider httpOnly cookies)
292- Not using `.populate()` projection — returning entire related documents
293- Forgetting `{ new: true }` on `findByIdAndUpdate` (returns old document by default)
294