Proxy Configuration for IP Detection

When deploying behind proxies (like Vercel, Cloudflare, AWS ALB, etc.), accurate client IP detection is crucial for rate limiting and connection limits. Without proper proxy configuration, the system might identify the proxy server's IP instead of the real client IP.

Configuration

Use the trustProxyDepth setting in your helium.config.ts:

1import type { HeliumConfig } from "heliumts/server";
2
3const config: HeliumConfig = {
4    trustProxyDepth: 1, // Set based on your deployment
5};
6
7export default config;

How It Works

Helium checks multiple headers to extract the client IP, in order of reliability:

1. CF-Connecting-IP - Cloudflare's guaranteed client IP
2. True-Client-IP - Cloudflare Enterprise and Akamai
3. X-Real-IP - Set by Nginx and other proxies
4. X-Forwarded-For - Standard header containing IP chain
5. req.socket.remoteAddress - Direct connection IP (fallback)

Common Deployment Scenarios

Vercel / Netlify / Railway / DigitalOcean APPs

trustProxyDepth: 1

These platforms add one proxy layer.

Cloudflare → Your Server

trustProxyDepth: 1

Helium automatically uses the CF-Connecting-IP header.

Cloudflare → Nginx → Node.js

trustProxyDepth: 2

With two proxy layers (Nginx + Cloudflare).

Local Development

trustProxyDepth: 0 (Default)

No proxies in local development.

Security Considerations

• Setting trustProxyDepth Too Low: Rate limiting will apply to the proxy IP, affecting all users.
• Setting trustProxyDepth Too High: Potential security risk if X-Forwarded-For is spoofed.

Best Practice: Always set trustProxyDepth to match your exact proxy configuration.