git:20251017.65e5cb0 to git:20260119.5684887

---

name: nodejs-backend-patterns

description: Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices. Use when creating Node.js servers, REST APIs, GraphQL backends, or microservices architectures.

---

# Node.js Backend Patterns

Comprehensive guidance for building scalable, maintainable, and production-ready Node.js backend applications with modern frameworks, architectural patterns, and best practices.

## When to Use This Skill

- Building REST APIs or GraphQL servers

- Creating microservices with Node.js

- Implementing authentication and authorization

- Designing scalable backend architectures

- Setting up middleware and error handling

- Integrating databases (SQL and NoSQL)

- Building real-time applications with WebSockets

- Implementing background job processing

## Core Frameworks

### Express.js - Minimalist Framework

**Basic Setup:**

```typescript

const app = express();

// Security middleware

app.use(helmet());

app.use(compression());

// Body parsing

// Request logging

app.use((req: Request, res: Response, next: NextFunction) => {

console.log(`${req.method} ${req.path}`);

next();

});

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {

console.log(`Server running on port ${PORT}`);

});

```

### Fastify - High Performance Framework

**Basic Setup:**

```typescript

const fastify = Fastify({

logger: {

transport: {

});

// Plugins

await fastify.register(helmet);

await fastify.register(cors, { origin: true });

await fastify.register(compress);

// Type-safe routes with schema validation

fastify.post<{

Body: { name: string; email: string };

Reply: { id: string; name: string };

```

## Architectural Patterns

### Pattern 1: Layered Architecture

**Structure:**

```

src/

├── controllers/ # Handle HTTP requests/responses

├── services/ # Business logic

├── repositories/ # Data access layer

├── models/ # Data models

├── middleware/ # Express/Fastify middleware

├── routes/ # Route definitions

├── utils/ # Helper functions

├── config/ # Configuration

└── types/ # TypeScript types

```

**Controller Layer:**

```typescript

// controllers/user.controller.ts

export class UserController {

constructor(private userService: UserService) {}

async createUser(req: Request, res: Response, next: NextFunction) {

try {

const userData: CreateUserDTO = req.body;

const user = await this.userService.createUser(userData);

res.status(201).json(user);

} catch (error) {

next(error);

}

}

async getUser(req: Request, res: Response, next: NextFunction) {

try {

const { id } = req.params;

const user = await this.userService.getUserById(id);

res.json(user);

} catch (error) {

next(error);

}

}

async updateUser(req: Request, res: Response, next: NextFunction) {

try {

const { id } = req.params;

const updates: UpdateUserDTO = req.body;

const user = await this.userService.updateUser(id, updates);

res.json(user);

} catch (error) {

next(error);

}

}

async deleteUser(req: Request, res: Response, next: NextFunction) {

try {

const { id } = req.params;

await this.userService.deleteUser(id);

res.status(204).send();

} catch (error) {

next(error);

}

}

}

```

**Service Layer:**

```typescript

// services/user.service.ts

export class UserService {

constructor(private userRepository: UserRepository) {}

async createUser(userData: CreateUserDTO): Promise<User> {

// Validation

const existingUser = await this.userRepository.findByEmail(userData.email);

if (existingUser) {

}

// Hash password

const hashedPassword = await bcrypt.hash(userData.password, 10);

// Create user

const user = await this.userRepository.create({

...userData,

});

// Remove password from response

const { password, ...userWithoutPassword } = user;

return userWithoutPassword as User;

}

async getUserById(id: string): Promise<User> {

const user = await this.userRepository.findById(id);

if (!user) {

}

const { password, ...userWithoutPassword } = user;

return userWithoutPassword as User;

}

async updateUser(id: string, updates: UpdateUserDTO): Promise<User> {

const user = await this.userRepository.update(id, updates);

if (!user) {

}

const { password, ...userWithoutPassword } = user;

return userWithoutPassword as User;

}

async deleteUser(id: string): Promise<void> {

const deleted = await this.userRepository.delete(id);

if (!deleted) {

}

}

}

```

**Repository Layer:**

```typescript

// repositories/user.repository.ts

export class UserRepository {

constructor(private db: Pool) {}

const query = `

INSERT INTO users (name, email, password)

VALUES ($1, $2, $3)

RETURNING id, name, email, password, created_at, updated_at

`;

const { rows } = await this.db.query(query, [

userData.name,

userData.email,

]);

return rows[0];

}

async findById(id: string): Promise<UserEntity | null> {

const { rows } = await this.db.query(query, [id]);

return rows[0] || null;

}

async findByEmail(email: string): Promise<UserEntity | null> {

const { rows } = await this.db.query(query, [email]);

return rows[0] || null;

}

async update(id: string, updates: UpdateUserDTO): Promise<UserEntity | null> {

const fields = Object.keys(updates);

const values = Object.values(updates);

const setClause = fields

.map((field, idx) => `${field} = $${idx + 2}`)

const query = `

UPDATE users

SET ${setClause}, updated_at = CURRENT_TIMESTAMP

WHERE id = $1

RETURNING *

`;

const { rows } = await this.db.query(query, [id, ...values]);

return rows[0] || null;

}

async delete(id: string): Promise<boolean> {

const { rowCount } = await this.db.query(query, [id]);

return rowCount > 0;

}

}

```

### Pattern 2: Dependency Injection

**DI Container:**

```typescript

// di-container.ts

class Container {

private instances = new Map<string, any>();

register<T>(key: string, factory: () => T): void {

this.instances.set(key, factory);

}

resolve<T>(key: string): T {

const factory = this.instances.get(key);

if (!factory) {

throw new Error(`No factory registered for ${key}`);

}

return factory();

}

singleton<T>(key: string, factory: () => T): void {

let instance: T;

this.instances.set(key, () => {

if (!instance) {

instance = factory();

}

return instance;

});

}

}

export const container = new Container();

// Register dependencies

);

);

);

);

```

## Middleware Patterns

### Authentication Middleware

```typescript

// middleware/auth.middleware.ts

interface JWTPayload {

userId: string;

email: string;

}

declare global {

namespace Express {

interface Request {

user?: JWTPayload;

}

}

}

export const authenticate = async (

req: Request,

res: Response,

) => {

try {

if (!token) {

}

req.user = payload;

next();

} catch (error) {

}

};

export const authorize = (...roles: string[]) => {

return async (req: Request, res: Response, next: NextFunction) => {

if (!req.user) {

}

// Check if user has required role

if (!hasRole) {

}

next();

};

};

```

### Validation Middleware

```typescript

// middleware/validation.middleware.ts

export const validate = (schema: AnyZodObject) => {

return async (req: Request, res: Response, next: NextFunction) => {

try {

await schema.parseAsync({

body: req.body,

query: req.query,

});

next();

} catch (error) {

if (error instanceof ZodError) {

}));

} else {

next(error);

}

}

};

};

// Usage with Zod

const createUserSchema = z.object({

body: z.object({

name: z.string().min(1),

email: z.string().email(),

});

```

### Rate Limiting Middleware

```typescript

// middleware/rate-limit.middleware.ts

const redis = new Redis({

host: process.env.REDIS_HOST,

});

export const apiLimiter = rateLimit({

store: new RedisStore({

client: redis,

}),

windowMs: 15 * 60 * 1000, // 15 minutes

max: 100, // Limit each IP to 100 requests per windowMs

standardHeaders: true,

legacyHeaders: false,

});

export const authLimiter = rateLimit({

store: new RedisStore({

client: redis,

}),

windowMs: 15 * 60 * 1000,

max: 5, // Stricter limit for auth endpoints

skipSuccessfulRequests: true,

});

```

### Request Logging Middleware

```typescript

// middleware/logger.middleware.ts

const logger = pino({

transport: {

});

export const requestLogger = (

req: Request,

res: Response,

) => {

const start = Date.now();

// Log response when finished

const duration = Date.now() - start;

logger.info({

method: req.method,

url: req.url,

status: res.statusCode,

duration: `${duration}ms`,

});

});

next();

};

export { logger };

```

## Error Handling

### Custom Error Classes

```typescript

// utils/errors.ts

export class AppError extends Error {

constructor(

public message: string,

public statusCode: number = 500,

) {

super(message);

Object.setPrototypeOf(this, AppError.prototype);

Error.captureStackTrace(this, this.constructor);

}

}

export class ValidationError extends AppError {

super(message, 400);

}

}

export class NotFoundError extends AppError {

super(message, 404);

}

}

export class UnauthorizedError extends AppError {

super(message, 401);

}

}

export class ForbiddenError extends AppError {

super(message, 403);

}

}

export class ConflictError extends AppError {

constructor(message: string) {

super(message, 409);

}

}

```

### Global Error Handler

```typescript

// middleware/error-handler.ts

export const errorHandler = (

err: Error,

req: Request,

res: Response,

) => {

if (err instanceof AppError) {

return res.status(err.statusCode).json({

message: err.message,

});

}

// Log unexpected errors

logger.error({

error: err.message,

stack: err.stack,

url: req.url,

});

// Don't leak error details in production

res.status(500).json({

});

};

// Async error wrapper

export const asyncHandler = (

) => {

return (req: Request, res: Response, next: NextFunction) => {

Promise.resolve(fn(req, res, next)).catch(next);

};

};

```

## Database Patterns

### PostgreSQL with Connection Pool

```typescript

// config/database.ts

const poolConfig: PoolConfig = {

host: process.env.DB_HOST,

database: process.env.DB_NAME,

user: process.env.DB_USER,

password: process.env.DB_PASSWORD,

max: 20,

idleTimeoutMillis: 30000,

connectionTimeoutMillis: 2000,

};

export const pool = new Pool(poolConfig);

// Test connection

});

process.exit(-1);

});

// Graceful shutdown

export const closeDatabase = async () => {

await pool.end();

};

```

### MongoDB with Mongoose

```typescript

// config/mongoose.ts

const connectDB = async () => {

try {

await mongoose.connect(process.env.MONGODB_URI!, {

maxPoolSize: 10,

serverSelectionTimeoutMS: 5000,

socketTimeoutMS: 45000,

});

} catch (error) {

process.exit(1);

}

};

});

});

export { connectDB };

// Model example

interface IUser extends Document {

name: string;

email: string;

password: string;

createdAt: Date;

updatedAt: Date;

}

// Indexes

userSchema.index({ email: 1 });

```

### Transaction Pattern

```typescript

// services/order.service.ts

export class OrderService {

constructor(private db: Pool) {}

async createOrder(userId: string, items: any[]) {

const client = await this.db.connect();

try {

// Create order

const orderResult = await client.query(

);

const orderId = orderResult.rows[0].id;

// Create order items

for (const item of items) {

await client.query(

);

// Update inventory

await client.query(

);

}

return orderId;

} catch (error) {

throw error;

} finally {

client.release();

}

}

}

```

## Authentication & Authorization

### JWT Authentication

```typescript

// services/auth.service.ts

export class AuthService {

constructor(private userRepository: UserRepository) {}

async login(email: string, password: string) {

const user = await this.userRepository.findByEmail(email);

if (!user) {

}

const isValid = await bcrypt.compare(password, user.password);

if (!isValid) {

}

const token = this.generateToken({

userId: user.id,

});

const refreshToken = this.generateRefreshToken({

});

return {

token,

refreshToken,

user: {

id: user.id,

name: user.name,

};

}

async refreshToken(refreshToken: string) {

try {

const payload = jwt.verify(

refreshToken,

) as { userId: string };

const user = await this.userRepository.findById(payload.userId);

if (!user) {

}

const token = this.generateToken({

userId: user.id,

});

return { token };

} catch (error) {

}

}

private generateToken(payload: any): string {

return jwt.sign(payload, process.env.JWT_SECRET!, {

});

}

private generateRefreshToken(payload: any): string {

return jwt.sign(payload, process.env.REFRESH_TOKEN_SECRET!, {

});

}

}

```

## Caching Strategies

```typescript

// utils/cache.ts

const redis = new Redis({

host: process.env.REDIS_HOST,

retryStrategy: (times) => {

const delay = Math.min(times * 50, 2000);

return delay;

});

export class CacheService {

async get<T>(key: string): Promise<T | null> {

const data = await redis.get(key);

return data ? JSON.parse(data) : null;

}

async set(key: string, value: any, ttl?: number): Promise<void> {

const serialized = JSON.stringify(value);

if (ttl) {

await redis.setex(key, ttl, serialized);

} else {

await redis.set(key, serialized);

}

}

async delete(key: string): Promise<void> {

await redis.del(key);

}

async invalidatePattern(pattern: string): Promise<void> {

const keys = await redis.keys(pattern);

if (keys.length > 0) {

await redis.del(...keys);

}

}

}

// Cache decorator

export function Cacheable(ttl: number = 300) {

return function (

target: any,

propertyKey: string,

) {

const originalMethod = descriptor.value;

descriptor.value = async function (...args: any[]) {

const cache = new CacheService();

const cacheKey = `${propertyKey}:${JSON.stringify(args)}`;

const cached = await cache.get(cacheKey);

if (cached) {

return cached;

}

const result = await originalMethod.apply(this, args);

await cache.set(cacheKey, result, ttl);

return result;

};

return descriptor;

};

}

```

## API Response Format

```typescript

// utils/response.ts

export class ApiResponse {

return res.status(statusCode).json({

message,

});

}

static error(res: Response, message: string, statusCode = 500, errors?: any) {

return res.status(statusCode).json({

message,

});

}

static paginated<T>(

res: Response,

data: T[],

page: number,

limit: number,

) {

return res.json({

data,

pagination: {

page,

limit,

total,

});

}

}

```

## Best Practices

1. **Use TypeScript**: Type safety prevents runtime errors

2. **Implement proper error handling**: Use custom error classes

3. **Validate input**: Use libraries like Zod or Joi

4. **Use environment variables**: Never hardcode secrets

5. **Implement logging**: Use structured logging (Pino, Winston)

6. **Add rate limiting**: Prevent abuse

7. **Use HTTPS**: Always in production

8. **Implement CORS properly**: Don't use `*` in production

9. **Use dependency injection**: Easier testing and maintenance

10. **Write tests**: Unit, integration, and E2E tests

11. **Handle graceful shutdown**: Clean up resources

12. **Use connection pooling**: For databases

13. **Implement health checks**: For monitoring

14. **Use compression**: Reduce response size

15. **Monitor performance**: Use APM tools

## Testing Patterns

See `javascript-testing-patterns` skill for comprehensive testing guidance.

## Resources

- **Node.js Best Practices**: https://github.com/goldbergyoni/nodebestpractices

- **Express.js Guide**: https://expressjs.com/en/guide/

- **Fastify Documentation**: https://www.fastify.io/docs/

- **TypeScript Node Starter**: https://github.com/microsoft/TypeScript-Node-Starter