Node.js Best Practices: Performance & Security Guide (2026)

Node.js powers backends at Netflix, PayPal, LinkedIn, and Walmart. Its event-driven, non-blocking architecture handles concurrent connections efficiently, but building a production-grade Node.js application requires more than just writing code that works. It requires patterns that keep working under load, under attack, and under the pressure of a growing codebase.

This guide covers the practices that separate a side project from a production system. Every recommendation is something you can apply today, with code examples you can adapt for your own stack.

Project Structure That Scales

A well-organized project is easier to navigate, test, and maintain. The goal is to separate concerns so that changes in one layer do not ripple through others.

project-root/
  src/
    routes/          # HTTP route definitions
    controllers/     # Request/response handling
    services/        # Business logic
    models/          # Data access and schemas
    middleware/       # Express middleware
    utils/           # Shared helpers
    config/          # Configuration loaders
    types/           # TypeScript type definitions
  test/
    unit/
    integration/
    e2e/
  scripts/           # Build and deploy scripts
  docker/            # Dockerfiles and compose
  package.json
  tsconfig.json
  .env.example

Layer Responsibilities

Routes define endpoints and wire them to controllers. They should contain no business logic. Controllers parse the request, call the appropriate service, and format the response. Services contain the actual business logic and are framework-agnostic, meaning they do not import Express or any HTTP library. Models handle data persistence and validation at the schema level.

// src/routes/user.routes.js
import { Router } from 'express';
import { getUser, createUser } from '../controllers/user.controller.js';
import { authenticate } from '../middleware/auth.js';
import { validate } from '../middleware/validate.js';
import { createUserSchema } from '../schemas/user.schema.js';

const router = Router();
router.get('/:id', authenticate, getUser);
router.post('/', authenticate, validate(createUserSchema), createUser);

export default router;

// src/controllers/user.controller.js
import * as userService from '../services/user.service.js';

export async function getUser(req, res, next) {
  try {
    const user = await userService.findById(req.params.id);
    if (!user) return res.status(404).json({ error: 'User not found' });
    res.json(user);
  } catch (err) {
    next(err);
  }
}

export async function createUser(req, res, next) {
  try {
    const user = await userService.create(req.body);
    res.status(201).json(user);
  } catch (err) {
    next(err);
  }
}

This separation means your services can be unit tested without spinning up an HTTP server, and you can swap Express for Fastify without rewriting your business logic.

Error Handling Done Right

Unhandled errors crash your process. Poor error handling leaks internal details to attackers. A solid strategy catches everything and responds predictably.

Custom Error Classes

// src/utils/errors.js
export class AppError extends Error {
  constructor(message, statusCode = 500, isOperational = true) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = isOperational;
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

export class NotFoundError extends AppError {
  constructor(resource = 'Resource') {
    super(`${resource} not found`, 404);
  }
}

export class ValidationError extends AppError {
  constructor(message) {
    super(message, 400);
  }
}

export class UnauthorizedError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, 401);
  }
}

Global Error Middleware

// src/middleware/errorHandler.js
import { AppError } from '../utils/errors.js';
import logger from '../utils/logger.js';

export function errorHandler(err, req, res, next) {
  // Default to 500 internal server error
  let statusCode = err.statusCode || 500;
  let message = err.message || 'Internal server error';

  // Log programming errors with full stack trace
  if (!err.isOperational) {
    logger.error('Unexpected error:', { err, stack: err.stack });
    message = 'Internal server error'; // Hide details from client
  }

  res.status(statusCode).json({
    status: 'error',
    message,
    ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
  });
}

Process-Level Safety

// src/index.js
process.on('unhandledRejection', (reason) => {
  logger.error('Unhandled Rejection:', reason);
  // Graceful shutdown
  server.close(() => process.exit(1));
});

process.on('uncaughtException', (err) => {
  logger.error('Uncaught Exception:', err);
  // Must exit - state is unreliable
  server.close(() => process.exit(1));
});

Security: Helmet, Rate Limiting, Input Validation

Security is not a feature you add at the end. It is a set of defaults you start with.

HTTP Security Headers with Helmet

import helmet from 'helmet';

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      imgSrc: ["'self'", "data:", "https:"],
    }
  },
  crossOriginEmbedderPolicy: true,
  crossOriginOpenerPolicy: true,
  crossOriginResourcePolicy: { policy: "same-origin" },
  hsts: { maxAge: 31536000, includeSubDomains: true, preload: true }
}));

Rate Limiting

import rateLimit from 'express-rate-limit';

const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,                  // 100 requests per window
  standardHeaders: true,
  legacyHeaders: false,
  message: { error: 'Too many requests, try again later' }
});

const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 5,  // Strict limit on auth endpoints
  message: { error: 'Too many login attempts' }
});

app.use('/api/', apiLimiter);
app.use('/api/auth/login', authLimiter);

Input Validation with Zod

import { z } from 'zod';

const createUserSchema = z.object({
  email: z.string().email().max(255),
  password: z.string().min(8).max(128),
  name: z.string().min(1).max(100).trim(),
});

// Validation middleware
function validate(schema) {
  return (req, res, next) => {
    const result = schema.safeParse(req.body);
    if (!result.success) {
      return res.status(400).json({
        error: 'Validation failed',
        details: result.error.flatten().fieldErrors
      });
    }
    req.body = result.data; // Use parsed and cleaned data
    next();
  };
}

Use the JWT Decoder to inspect token payloads during development without exposing secrets or using third-party websites.

Performance: Clustering, Caching, Streams

Node.js runs on a single thread by default. To use all CPU cores, you need clustering. To avoid redundant work, you need caching. To handle large data efficiently, you need streams.

Clustering with the Cluster Module

import cluster from 'node:cluster';
import { availableParallelism } from 'node:os';

const numCPUs = availableParallelism();

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} starting ${numCPUs} workers`);

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code) => {
    console.log(`Worker ${worker.process.pid} exited (code: ${code})`);
    cluster.fork(); // Replace dead workers
  });
} else {
  // Workers share the TCP connection
  app.listen(3000, () => {
    console.log(`Worker ${process.pid} listening`);
  });
}

In-Memory Caching

import { LRUCache } from 'lru-cache';

const cache = new LRUCache({
  max: 500,               // Maximum 500 entries
  ttl: 1000 * 60 * 5,     // 5-minute TTL
  allowStale: false,
});

async function getCachedUser(id) {
  const cacheKey = `user:${id}`;
  const cached = cache.get(cacheKey);
  if (cached) return cached;

  const user = await db.users.findById(id);
  if (user) cache.set(cacheKey, user);
  return user;
}

Streams for Large Data

import { createReadStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import { createGzip } from 'node:zlib';

// Stream a large file instead of loading it into memory
app.get('/export/:id', async (req, res) => {
  const filePath = await getExportPath(req.params.id);

  res.setHeader('Content-Type', 'application/gzip');
  res.setHeader('Content-Disposition', 'attachment; filename="export.csv.gz"');

  await pipeline(
    createReadStream(filePath),
    createGzip(),
    res
  );
});

Async Patterns and Concurrency

Modern Node.js uses async/await for virtually all asynchronous operations. The remaining skill is knowing how to run things concurrently without overwhelming external services.

Concurrent Operations

// Run independent operations concurrently
const [user, orders, notifications] = await Promise.all([
  userService.findById(userId),
  orderService.findByUser(userId),
  notificationService.getUnread(userId),
]);

// Handle partial failures
const results = await Promise.allSettled([
  sendEmail(user.email),
  sendSMS(user.phone),
  sendPushNotification(user.deviceToken),
]);

const failures = results
  .filter(r => r.status === 'rejected')
  .map(r => r.reason);

if (failures.length) logger.warn('Notification failures:', failures);

Controlled Concurrency

// Process items in batches to avoid overwhelming a database
async function processBatch(items, batchSize, fn) {
  const results = [];
  for (let i = 0; i < items.length; i += batchSize) {
    const batch = items.slice(i, i + batchSize);
    const batchResults = await Promise.all(batch.map(fn));
    results.push(...batchResults);
  }
  return results;
}

// Process 1000 users, 50 at a time
await processBatch(userIds, 50, async (id) => {
  return userService.syncProfile(id);
});

For validating the configuration files that control your async workers and job queues, the YAML Editor catches syntax errors before they hit production.

Testing Strategy

A reliable test suite has three layers: fast unit tests for business logic, integration tests for service interactions, and a thin layer of end-to-end tests for critical paths.

// test/unit/services/user.service.test.js
import { describe, it, expect, vi } from 'vitest';
import * as userService from '../../../src/services/user.service.js';
import * as userModel from '../../../src/models/user.model.js';

vi.mock('../../../src/models/user.model.js');

describe('userService.create', () => {
  it('hashes the password before saving', async () => {
    userModel.create.mockResolvedValue({ id: '1', email: 'a@b.com' });

    const result = await userService.create({
      email: 'a@b.com',
      password: 'securepass123'
    });

    const savedArg = userModel.create.mock.calls[0][0];
    expect(savedArg.password).not.toBe('securepass123');
    expect(savedArg.password).toMatch(/^\$2[aby]\$/); // bcrypt hash
    expect(result.id).toBe('1');
  });

  it('throws on duplicate email', async () => {
    userModel.create.mockRejectedValue({ code: 11000 });
    await expect(userService.create({ email: 'dup@b.com', password: 'x' }))
      .rejects.toThrow('Email already exists');
  });
});

// test/integration/routes/user.routes.test.js
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import request from 'supertest';
import { app } from '../../../src/app.js';
import { setupTestDB, teardownTestDB } from '../../helpers/db.js';

beforeAll(() => setupTestDB());
afterAll(() => teardownTestDB());

describe('POST /api/users', () => {
  it('returns 201 with valid data', async () => {
    const res = await request(app)
      .post('/api/users')
      .send({ email: 'new@example.com', password: 'Str0ng!Pass', name: 'Test' })
      .set('Authorization', `Bearer ${testToken}`);

    expect(res.status).toBe(201);
    expect(res.body).toHaveProperty('id');
    expect(res.body.email).toBe('new@example.com');
  });

  it('returns 400 for invalid email', async () => {
    const res = await request(app)
      .post('/api/users')
      .send({ email: 'not-an-email', password: 'test', name: 'Test' })
      .set('Authorization', `Bearer ${testToken}`);

    expect(res.status).toBe(400);
  });
});

Scaffold your ESLint configuration with testing rules using the ESLint Config Generator. It supports Vitest, Jest, and Mocha presets.

Environment Variables and Configuration

Configuration should come from the environment, not from hardcoded values. This lets the same code run in development, staging, and production with different settings.

// src/config/index.js
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional(),
  JWT_SECRET: z.string().min(32),
  JWT_EXPIRY: z.string().default('15m'),
  CORS_ORIGIN: z.string().default('http://localhost:3000'),
  LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
});

const parsed = envSchema.safeParse(process.env);

if (!parsed.success) {
  console.error('Invalid environment variables:', parsed.error.flatten());
  process.exit(1);
}

export const config = Object.freeze(parsed.data);

The Env File Editor helps you manage .env files with syntax highlighting, validation, and the ability to compare different environment configurations side by side.

Production Deployment

Multi-Stage Dockerfile

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine AS production
WORKDIR /app
RUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -s /bin/sh -D appuser
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --only=production && npm cache clean --force
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

Graceful Shutdown

function gracefulShutdown(signal) {
  console.log(`${signal} received. Starting graceful shutdown...`);

  server.close(async () => {
    console.log('HTTP server closed');

    // Close database connections
    await db.disconnect();
    console.log('Database disconnected');

    // Close Redis
    await redis.quit();
    console.log('Redis disconnected');

    process.exit(0);
  });

  // Force exit after 30 seconds
  setTimeout(() => {
    console.error('Forced shutdown after timeout');
    process.exit(1);
  }, 30000);
}

process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT', () => gracefulShutdown('SIGINT'));

Generate your Docker Compose configuration for Node.js with databases, Redis, and reverse proxies using the Docker Compose Generator.

Logging and Monitoring

In production, console.log is not enough. Use a structured logging library that outputs JSON, so your log aggregator can parse, search, and alert on specific fields.

import pino from 'pino';

const logger = pino({
  level: config.LOG_LEVEL,
  transport: config.NODE_ENV === 'development'
    ? { target: 'pino-pretty' }
    : undefined,
  serializers: {
    err: pino.stdSerializers.err,
    req: pino.stdSerializers.req,
    res: pino.stdSerializers.res,
  }
});

// Usage
logger.info({ userId: user.id, action: 'login' }, 'User logged in');
logger.error({ err, orderId }, 'Payment processing failed');

Health Check Endpoint

app.get('/health', async (req, res) => {
  const checks = {
    uptime: process.uptime(),
    timestamp: Date.now(),
    database: 'unknown',
    redis: 'unknown',
  };

  try {
    await db.raw('SELECT 1');
    checks.database = 'healthy';
  } catch {
    checks.database = 'unhealthy';
  }

  try {
    await redis.ping();
    checks.redis = 'healthy';
  } catch {
    checks.redis = 'unhealthy';
  }

  const isHealthy = checks.database === 'healthy';
  res.status(isHealthy ? 200 : 503).json(checks);
});

Related Developer Tools

Free browser-based tools for your Node.js development workflow.

---