Production-Ready Node.js Config

Comprehensive Node.js development setting optimizing runtime configuration, security headers, and performance tuning for production workloads.

When to Use This Setting

Apply this setting when you need to:

• Configure Node.js runtime options for production deployment with optimized memory limits and garbage collection
• Apply security best practices including helmet headers, rate limiting, and input validation middleware
• Tune performance parameters like cluster mode, connection pooling, and request timeout thresholds Consider alternatives when:
• Your Node.js application runs only in development or testing environments where production hardening is unnecessary
• You use a managed platform like Vercel or AWS Lambda that handles runtime configuration automatically

Quick Start

Configuration

Copy
name: production-ready-nodejs-config
type: setting
category: development

Example Application

Copy
claude setting:apply production-ready-nodejs-config

Example Output

Setting applied. Changes:
- NODE_ENV: production
- node_options: --max-old-space-size=4096
- cluster_mode: enabled (workers = CPU count)
- security: helmet + rate-limit + cors
- logging: structured JSON with log levels

Core Concepts

Production Node.js Overview

Aspect	Details
Runtime Optimization	V8 heap size, garbage collection flags, and UV thread pool tuning
Cluster Mode	Forks worker processes matching CPU core count for multi-core utilization
Security Middleware	Helmet for HTTP headers, express-rate-limit for abuse prevention, cors for origin control
Structured Logging	JSON-formatted logs with levels (error, warn, info, debug) for log aggregation
Health Monitoring	Liveness and readiness endpoints for container orchestration health checks

Production Architecture

+-------------------+     +---------------------+     +-------------------+
| Node.js Runtime   |---->| Cluster Manager     |---->| Worker Processes  |
| --max-old-space   |     | fork per CPU core   |     | request handling  |
| --optimize-for    |     | worker restart on   |     | middleware chain  |
| production flags  |     | crash or OOM        |     | route processing  |
+-------------------+     +---------------------+     +-------------------+
         |                          |                          |
         v                          v                          v
  +----------------+      +-------------------+      +-------------------+
  | Security Layer |      | Logging Pipeline  |      | Health Endpoints  |
  | helmet + rate  |      | structured JSON   |      | /healthz          |
  | limit + cors   |      | log levels        |      | /readyz           |
  +----------------+      +-------------------+      +-------------------+

Configuration

Parameter	Type	Default	Description
max_old_space_size	integer	4096	V8 heap size limit in megabytes for the old generation space
cluster_workers	string	"auto"	Number of worker processes; auto uses os.cpus().length
rate_limit_window	integer	900000	Rate limiting window in milliseconds (15 minutes default)
rate_limit_max	integer	100	Maximum requests per window per IP address
log_level	string	"info"	Minimum log level for production: error, warn, info, or debug

Best Practices

1. Set memory limits based on container allocation - If running in Docker or Kubernetes, set max_old_space_size to 75% of the container memory limit. This leaves room for the operating system and prevents OOM kills that would terminate the container abruptly.
2. Use cluster mode with sticky sessions - If your application uses sessions or WebSocket connections, configure your load balancer for sticky sessions so requests from the same client always route to the same worker process.
3. Apply rate limiting per route - The global rate limit provides baseline protection, but apply stricter limits on sensitive endpoints like authentication and payment. Set login endpoints to 5 attempts per 15 minutes and payment to 10 per hour.
4. Implement graceful shutdown - Handle SIGTERM signals in your worker processes to finish in-flight requests before exiting. This prevents dropped connections during deployments and pod termination in Kubernetes.
5. Use structured logging in production - Replace console.log with a structured logger like pino or winston configured for JSON output. This enables your log aggregation platform to parse, index, and search log data effectively.

Common Issues

1. Application crashes with heap out of memory - The max_old_space_size is too low for your workload. Increase the value in increments of 1024MB and monitor memory usage with process.memoryUsage() to find the right threshold.
2. Rate limiting blocks legitimate users - The default 100 requests per 15 minutes may be too restrictive for API-heavy applications. Increase rate_limit_max or implement per-user rate limits instead of per-IP to avoid blocking shared office networks.
3. Cluster workers restart continuously - A worker crashing immediately after fork indicates a startup error in your application code. Check the worker error logs for the root cause and fix the application error before relying on cluster restart to mask it.