Express.js Project

---
applyTo: "**/*.js, **/*.ts"
---

# Express.js Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up the latest Express documentation: https://expressjs.com
- Use Express 4+ or Express 5 (when stable) with TypeScript for type safety
- Follow RESTful API design principles
- Implement middleware pattern for cross-cutting concerns
- Use async/await with proper error handling
- Implement request validation and sanitization

**Core Principles:**

- Organize routes with express.Router() for modularity
- Implement layered architecture (Routes → Controllers → Services → Data Access)
- Use middleware for authentication, logging, error handling
- Follow single responsibility principle for route handlers
- Use environment variables for configuration (dotenv)

**Routing:**

- Define routes with proper HTTP methods (GET, POST, PUT, DELETE, PATCH)
- Use route parameters and query strings appropriately
- Implement route versioning (e.g., /api/v1/users)
- Group related routes with Router
- Use route-specific middleware

**Middleware:**

- Use built-in middleware (express.json(), express.urlencoded())
- Implement custom middleware for logging, authentication, authorization
- Order middleware correctly (global → route-specific)
- Use error-handling middleware with 4 parameters
- Implement request timeout and rate limiting

**Error Handling:**

- Use async error handling with try-catch or express-async-errors
- Implement centralized error handling middleware
- Return consistent error response format
- Log errors with appropriate context
- Use HTTP status codes correctly

**Security:**

- Use helmet.js for security headers
- Implement CORS with cors middleware
- Use express-rate-limit for rate limiting
- Validate and sanitize inputs with express-validator or joi
- Implement authentication with JWT or session-based auth
- Use HTTPS in production

**Database:**

- Use connection pooling for database connections
- Implement repository pattern or use an ORM (Prisma, TypeORM, Sequelize)
- Handle database errors gracefully
- Use transactions for atomic operations
- Implement database migrations

**Testing:**

- Use Jest or Vitest for unit testing
- Use supertest for API endpoint testing
- Mock external dependencies
- Test middleware and route handlers separately
- Implement integration tests for critical flows

**Performance:**

- Use compression middleware for response compression
- Implement caching strategies (Redis, memory cache)
- Use clustering for multi-core support
- Optimize database queries
- Use streaming for large responses

**Logging:**

- Use structured logging (Winston, Pino)
- Log request/response details for debugging
- Implement log levels (error, warn, info, debug)
- Use correlation IDs for request tracking
- Avoid logging sensitive data

**Summary:**

> For all Express.js work, always use the fetch tool to look up the latest documentation from https://expressjs.com. Write secure, performant, and maintainable API code.