Node.js Production Best Practices and Checklist

Your Node.js application passed all tests and code reviews. Two hours into production, the health check endpoint returns 503, logs are streaming to stdout with no log rotation, environment variables are hardcoded in the source code, and the database connection pool is exhausted because pool size was never configured. A production checklist transforms deployment from guesswork into a repeatable process. This article compiles every check you need before going live: security, performance, observability, reliability, and operational readiness.

1. Process Management and Clustering

In production, a single Node.js process is a single point of failure. Use a process manager like PM2 to run your app in cluster mode, spawning multiple instances across CPU cores. This ensures zero-downtime restarts, graceful shutdown, and automatic recovery from crashes. Configure instances: 'max' to utilize all cores. Set max_memory_restart to prevent memory leaks from taking down the server. Always use --max-old-space-size to limit V8 heap. Without clustering, a single uncaught exception or memory spike kills your entire service. PM2 also provides log management and monitoring hooks.

module.exports = {
  apps: [{
    name: 'my-app',
    script: 'dist/server.js',
    instances: 'max',
    exec_mode: 'cluster',
    max_memory_restart: '500M',
    env: {
      NODE_ENV: 'production',
      NODE_OPTIONS: '--max-old-space-size=512'
    },
    kill_timeout: 5000,
    listen_timeout: 3000
  }]
};

2. Environment Configuration Management

Never hardcode secrets or environment-specific values. Use environment variables with a library like dotenv for local development, but in production, inject variables via the deployment platform (e.g., Kubernetes secrets, AWS Parameter Store). Validate all required variables at startup using a schema (e.g., joi or env-var). This prevents silent failures when a config is missing. Also, separate config by environment: development, staging, production. Use a single source of truth like a config module that reads from process.env and exports typed values. Avoid using .env files in production — they can be accidentally committed.

const envalid = require('envalid');
const { str, num, bool } = envalid;

const env = envalid.cleanEnv(process.env, {
  NODE_ENV: str({ choices: ['development', 'production', 'test'] }),
  PORT: num({ default: 3000 }),
  DB_URL: str(),
  REDIS_URL: str(),
  JWT_SECRET: str(),
  ENABLE_LOGGING: bool({ default: true })
});

module.exports = {
  port: env.PORT,
  dbUrl: env.DB_URL,
  redisUrl: env.REDIS_URL,
  jwtSecret: env.JWT_SECRET,
  isProduction: env.NODE_ENV === 'production',
  enableLogging: env.ENABLE_LOGGING
};

3. Error Handling and Uncaught Exceptions

Node.js crashes on uncaught exceptions. Always use a global error handler for uncaught exceptions and unhandled promise rejections. However, these handlers should log the error and then gracefully shut down the process — the process is in an unknown state. Use a process manager to restart. For operational errors (e.g., invalid input), use a centralized error-handling middleware in Express. Return consistent JSON error responses with appropriate HTTP status codes. Never expose stack traces in production. Use libraries like http-errors to create error objects. Also, handle async errors by wrapping route handlers with a catch-all.

const createError = require('http-errors');

// Async wrapper
const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

// Centralized error handler
const errorHandler = (err, req, res, next) => {
  const statusCode = err.status || 500;
  const message = err.message || 'Internal Server Error';

  // Log full error
  console.error(`[${new Date().toISOString()}] ${err.stack}`);

  res.status(statusCode).json({
    error: {
      message: process.env.NODE_ENV === 'production' ? 'Something went wrong' : message,
      status: statusCode
    }
  });
};

// Global uncaught handlers
process.on('uncaughtException', (err) => {
  console.error('Uncaught Exception:', err);
  process.exit(1);
});

process.on('unhandledRejection', (reason) => {
  console.error('Unhandled Rejection:', reason);
  process.exit(1);
});

module.exports = { asyncHandler, errorHandler };

4. Logging and Monitoring

Console.log is not enough for production. Use structured logging with a library like pino or winston. Log in JSON format so log aggregators (ELK, Datadog) can parse them. Include correlation IDs for request tracing. Log at appropriate levels: error, warn, info, debug. Never log sensitive data (passwords, tokens). Set up health check endpoints (e.g., /health) that return status of database, cache, and external services. Use APM tools like New Relic or Sentry for performance monitoring. Monitor memory usage, event loop lag, and garbage collection. Alerts should trigger on error rate spikes or high latency.

const pino = require('pino');

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  formatters: {
    level: (label) => ({ level: label })
  },
  timestamp: pino.stdTimeFunctions.isoTime,
  redact: ['req.headers.authorization', 'req.body.password']
});

// Express middleware to log requests
const requestLogger = (req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    logger.info({
      method: req.method,
      url: req.originalUrl,
      status: res.statusCode,
      duration: Date.now() - start,
      correlationId: req.headers['x-correlation-id']
    });
  });
  next();
};

module.exports = { logger, requestLogger };

5. Security Best Practices

Production Node.js apps are frequent targets. Always use Helmet to set secure HTTP headers. Validate and sanitize all user input to prevent injection attacks. Use parameterized queries for databases. Implement rate limiting to prevent brute-force attacks. Use express-rate-limit or a reverse proxy like Nginx. Set up CORS properly — don't use wildcard in production. Use environment-specific CORS origins. Encrypt sensitive data at rest and in transit. Use bcrypt for password hashing. Keep dependencies updated with npm audit and use a tool like Snyk. Disable X-Powered-By header. Use csurf for CSRF protection if using cookies.

const express = require('express');
const helmet = require('helmet');
const rateLimit = require('express-rate-limit');
const cors = require('cors');

const app = express();

// Security headers
app.use(helmet());

// CORS
app.use(cors({
  origin: process.env.CORS_ORIGIN || 'https://myapp.com',
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization']
}));

// Rate limiting
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,
  message: 'Too many requests, please try again later.'
});
app.use('/api/', limiter);

// Remove fingerprinting
app.disable('x-powered-by');

// Input validation middleware (example)
const validateInput = (req, res, next) => {
  const { email } = req.body;
  if (email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
    return res.status(400).json({ error: 'Invalid email format' });
  }
  next();
};

6. Database Connection Management

Database connections are expensive. Use a connection pool (e.g., pg-pool for PostgreSQL, mongoose for MongoDB) to reuse connections. Set pool size based on your database's max connections and your app's concurrency. Monitor pool usage — if you exhaust connections, requests will queue or fail. Use retry logic with exponential backoff for transient failures. Always close connections gracefully on shutdown. For read-heavy workloads, consider read replicas. Use environment-specific pool settings: smaller pool in development, larger in production. Also, use connection strings with SSL enabled in production.

const { Pool } = require('pg');

const pool = new Pool({
  connectionString: process.env.DB_URL,
  max: 20, // max connections in pool
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
  ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: true } : false
});

// Query wrapper with retry
async function query(text, params, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const result = await pool.query(text, params);
      return result;
    } catch (err) {
      if (i === retries - 1) throw err;
      console.warn(`Query failed, retrying (${i + 1}/${retries})`);
      await new Promise(res => setTimeout(res, 1000 * Math.pow(2, i)));
    }
  }
}

// Graceful shutdown
process.on('SIGTERM', async () => {
  await pool.end();
  process.exit(0);
});

module.exports = { query, pool };

7. Caching Strategies

Caching reduces load on databases and improves response times. Use in-memory caching (e.g., node-cache) for single-instance apps, but for clustered or multi-server setups, use a distributed cache like Redis. Cache database query results, computed values, and API responses. Set appropriate TTLs based on data staleness tolerance. Use cache-aside pattern: check cache first, if miss, fetch from source and populate cache. Implement cache invalidation carefully — stale data can cause bugs. For high-traffic endpoints, consider write-through or write-behind caching. Monitor cache hit rates; low hit rates indicate poor cache strategy.

const redis = require('redis');
const { promisify } = require('util');

const client = redis.createClient({
  url: process.env.REDIS_URL,
  socket: {
    tls: process.env.NODE_ENV === 'production',
    reconnectStrategy: (retries) => Math.min(retries * 100, 3000)
  }
});

client.on('error', (err) => console.error('Redis error:', err));

const getAsync = promisify(client.get).bind(client);
const setAsync = promisify(client.set).bind(client);

async function getOrSet(key, fetchFn, ttl = 60) {
  const cached = await getAsync(key);
  if (cached) return JSON.parse(cached);

  const data = await fetchFn();
  await setAsync(key, JSON.stringify(data), 'EX', ttl);
  return data;
}

module.exports = { getOrSet, client };

8. Graceful Shutdown and Health Checks

When your app receives a termination signal (SIGTERM from Kubernetes, PM2, etc.), you must shut down gracefully: stop accepting new requests, finish in-flight requests, close database connections, and then exit. Implement a health check endpoint that returns liveness and readiness. Liveness indicates the process is alive; readiness indicates it can serve traffic (e.g., database is connected). Kubernetes uses these to restart pods or stop routing traffic. Use http-shutdown or manual server closing. Set a timeout for forced exit to prevent hanging.

const http = require('http');
const app = require('./app');
const { pool } = require('./db');

const server = http.createServer(app);

// Health check endpoint
app.get('/health', async (req, res) => {
  try {
    await pool.query('SELECT 1');
    res.status(200).json({ status: 'healthy', uptime: process.uptime() });
  } catch (err) {
    res.status(503).json({ status: 'unhealthy' });
  }
});

// Graceful shutdown
async function shutdown(signal) {
  console.log(`Received ${signal}, shutting down gracefully...`);
  server.close(async () => {
    await pool.end();
    console.log('Closed all connections. Exiting.');
    process.exit(0);
  });

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

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

server.listen(process.env.PORT || 3000, () => {
  console.log(`Server listening on port ${process.env.PORT || 3000}`);
});

9. Dependency Management and CI/CD

Lock your dependencies with package-lock.json or yarn.lock. Use npm ci in CI for deterministic installs. Regularly run npm audit and fix vulnerabilities. Use a tool like snyk or dependabot for automated updates. In CI, run linting, tests, and security scans. Build artifacts (e.g., transpiled code) should be created in CI, not committed. Use multi-stage Docker builds to keep images small. Tag images with git commit hash for traceability. Deploy using blue-green or rolling updates. Automate rollback if health checks fail.

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY dist/ ./dist/
COPY package.json ./

EXPOSE 3000
USER node
CMD ["node", "dist/server.js"]

10. Performance Optimization and Profiling

Profile your app under load to find bottlenecks. Use Node.js built-in profiler (--prof) or tools like clinic.js. Common issues: synchronous operations blocking the event loop, excessive garbage collection, memory leaks, and slow database queries. Use async for I/O. Avoid JSON.parse on large payloads in the main thread — offload to worker threads if needed. Use streaming for large responses. Implement response compression with compression middleware. Set NODE_ENV=production to enable optimizations (view caching, etc.). Use clinic to generate flamegraphs. Monitor event loop lag with process.hrtime.

const compression = require('compression');
const responseTime = require('response-time');

// Compression
app.use(compression());

// Response time header
app.use(responseTime((req, res, time) => {
  console.log(`${req.method} ${req.originalUrl} ${time}ms`);
}));

// Event loop lag monitoring
let lastCheck = process.hrtime.bigint();
setInterval(() => {
  const now = process.hrtime.bigint();
  const lag = Number(now - lastCheck) / 1e6; // ms
  if (lag > 50) {
    console.warn(`Event loop lag: ${lag.toFixed(2)}ms`);
  }
  lastCheck = now;
}, 1000);

11. Testing for Production Reliability

Unit tests alone are not enough. Write integration tests that test your API endpoints with a real database. Use supertest for HTTP testing. Write contract tests for microservices. Implement smoke tests that run after deployment to verify the app is healthy. Use load testing (e.g., artillery or k6) to find breaking points. Test error scenarios: database down, external API failure, invalid input. Use test containers for database dependencies. Aim for high code coverage but focus on critical paths. Run tests in CI on every push.

const request = require('supertest');
const app = require('../src/app');
const { pool } = require('../src/db');

beforeAll(async () => {
  // Setup test database
  await pool.query('CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT)');
});

afterAll(async () => {
  await pool.query('DROP TABLE IF EXISTS users');
  await pool.end();
});

describe('POST /api/users', () => {
  it('should create a user', async () => {
    const res = await request(app)
      .post('/api/users')
      .send({ name: 'John' })
      .expect(201);
    expect(res.body).toHaveProperty('id');
  });

  it('should return 400 for invalid name', async () => {
    await request(app)
      .post('/api/users')
      .send({ name: '' })
      .expect(400);
  });
});

12. Deployment and Rollback Strategy

Use immutable deployments: build a new artifact (Docker image) for each version. Tag images with git commit hash. Use blue-green or canary deployments to minimize risk. Always have a rollback plan: keep the previous version running and switch back if health checks fail. Use feature flags to toggle features without redeploying. Automate the deployment pipeline with CI/CD (e.g., GitHub Actions, GitLab CI). Monitor error rates and latency after deployment. If error rate spikes, trigger automatic rollback. Document the rollback procedure.

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .
      - name: Push to registry
        run: docker push myapp:${{ github.sha }}
      - name: Deploy to Kubernetes
        run: |
          kubectl set image deployment/myapp myapp=myapp:${{ github.sha }}
          kubectl rollout status deployment/myapp
      - name: Smoke test
        run: |
          curl -f http://myapp.com/health || exit 1
      - name: Rollback on failure
        if: failure()
        run: kubectl rollout undo deployment/myapp

Security Headers with Helmet.js

Helmet.js is a middleware that sets various HTTP security headers to protect your Express app from common web vulnerabilities. It bundles 15 smaller middleware functions, including CSP, X-Frame-Options, and X-Content-Type-Options. In production, you should configure Helmet with strict policies. For example, set Content-Security-Policy to restrict script sources and disable inline scripts unless hashed. Use helmet.contentSecurityPolicy() with directives like defaultSrc: ["'self'"] and scriptSrc: ["'self'", "'strict-dynamic'"]. Avoid using 'unsafe-inline' in production. Also, enable referrerPolicy: 'same-origin' and hsts: { maxAge: 31536000, includeSubDomains: true, preload: true }. Test your headers with securityheaders.com. Remember that overly strict CSP can break third-party scripts, so iterate carefully.

const helmet = require('helmet');

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'strict-dynamic'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      imgSrc: ["'self'", "data:"],
      connectSrc: ["'self'"],
      fontSrc: ["'self'"],
      objectSrc: ["'none'"],
      upgradeInsecureRequests: []
    }
  },
  referrerPolicy: { policy: 'same-origin' },
  hsts: { maxAge: 31536000, includeSubDomains: true, preload: true }
}));

Rate Limiting with express-rate-limit

Rate limiting protects your API from abuse and brute-force attacks. Use express-rate-limit middleware to cap requests per IP. In production, set a generous limit for general endpoints (e.g., 100 requests per 15 minutes) and stricter limits for auth routes (e.g., 5 attempts per 15 minutes). Configure the middleware with windowMs, max, and a custom message. Use keyGenerator to rate-limit by user ID if authenticated. For distributed environments, use an external store like Redis via rate-limit-redis to share state across instances. Always return a Retry-After header. Monitor rate limit hits via logs or metrics. Avoid rate limiting health check endpoints. Example: create a separate limiter for /api/auth/login with max: 5 and windowMs: 15 60 1000.

const rateLimit = require('express-rate-limit');
const RedisStore = require('rate-limit-redis');
const redisClient = require('./redis');

const generalLimiter = rateLimit({
  store: new RedisStore({ client: redisClient }),
  windowMs: 15 * 60 * 1000,
  max: 100,
  standardHeaders: true,
  legacyHeaders: false,
  message: { error: 'Too many requests, please try again later.' }
});

const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 5,
  message: { error: 'Too many login attempts, please try again later.' },
  skipSuccessfulRequests: true
});

module.exports = { generalLimiter, authLimiter };

CORS Configuration

Cross-Origin Resource Sharing (CORS) controls which domains can access your API. In production, never use origin: '*'. Instead, whitelist specific origins. Use the cors package with an array of allowed origins or a function that validates the request origin. For example, origin: ['https://myapp.com', 'https://admin.myapp.com']. If you need to support dynamic origins (e.g., mobile apps), validate against a regex or a list. Also set credentials: true if using cookies or authorization headers. Restrict allowed methods (GET,POST,PUT,DELETE) and headers (Content-Type,Authorization). Set maxAge to cache preflight responses (e.g., 86400 seconds). For public APIs, consider using a reverse proxy to handle CORS. Always test with different origins in staging.

const cors = require('cors');

const allowedOrigins = ['https://myapp.com', 'https://admin.myapp.com'];

const corsOptions = {
  origin: (origin, callback) => {
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  maxAge: 86400
};

app.use(cors(corsOptions));

Input Validation and Sanitization

Always validate and sanitize user input to prevent injection attacks and data corruption. Use a schema validation library like Joi or Zod for request bodies, query params, and route params. Define strict schemas with expected types, lengths, and patterns. Sanitize strings to remove HTML tags using sanitize-html or xss. For MongoDB, use mongo-sanitize to prevent NoSQL injection. Never trust req.body, req.query, or req.params directly. Validate at the middleware level before any business logic. Return clear error messages but avoid exposing internal details. For file uploads, validate MIME types and file size. Use express-validator for simple cases, but prefer Joi for complex schemas. Example: validate email with Joi.string().email().required(). Always normalize Unicode characters to prevent homograph attacks.

const Joi = require('joi');

const userSchema = Joi.object({
  name: Joi.string().min(2).max(50).required(),
  email: Joi.string().email().required(),
  password: Joi.string().min(8).pattern(new RegExp('^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)')).required(),
  role: Joi.string().valid('user', 'admin').default('user')
});

function validateUser(req, res, next) {
  const { error } = userSchema.validate(req.body, { abortEarly: false });
  if (error) {
    return res.status(400).json({ errors: error.details.map(d => d.message) });
  }
  next();
}

app.post('/api/users', validateUser, handler);

Gzip Compression

Enable gzip compression to reduce response size and improve load times. Use the compression middleware in Express. In production, set compression level to 6 (balance between speed and ratio). Filter out already compressed responses (e.g., images, videos) using the filter option. For high-traffic apps, offload compression to a reverse proxy like Nginx. Test with curl -H "Accept-Encoding: gzip" -o /dev/null -w "%{size_download}" to compare sizes. Be aware that compression adds CPU overhead; monitor server load. For dynamic content, cache compressed responses in Redis. Example: app.use(compression({ level: 6, threshold: 1024 })) compresses responses larger than 1KB. Always set Vary: Accept-Encoding header (handled automatically).

const compression = require('compression');

app.use(compression({
  level: 6,
  threshold: 1024,
  filter: (req, res) => {
    if (req.headers['x-no-compression']) return false;
    return compression.filter(req, res);
  }
}));

Dependency Vulnerability Scanning

Regularly scan your dependencies for known vulnerabilities using npm audit and Snyk. Run npm audit in CI to fail builds on high-severity issues. Use npm audit fix to auto-fix where possible, but review changes. For deeper scanning, integrate Snyk into your pipeline: snyk test and snyk monitor. Snyk provides real-time alerts and fix PRs. Also scan your Docker images with snyk container test or Trivy. In your Dockerfile, use multi-stage builds to minimize attack surface. Pin base image versions (e.g., node:18-alpine). Regularly update dependencies with npm update or tools like Renovate. For production, consider using a private registry with vulnerability scanning. Example CI step: npm audit --audit-level=high exits with code 1 if any high severity found.

name: CI
on: [push]
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm audit --audit-level=high
      - name: Snyk Scan
        uses: snyk/actions/node@master
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}