Highlights ✨

• Checks 14 sources (headers + socket) in priority order
• Handles comma-separated, array, and RFC 7239 Forwarded formats
• Framework compatibility — supports Express v5/v4 and NestJS (Express adapter)
• Flexible usage — works standalone or as middleware, and auto-populates typed req.clientIp and req.clientIps
• Zero config — validates IPs using Node.js net.isIP()

Installation 📦

Requires Node.js >= 18.

npm install get-client-ip
# or
pnpm add get-client-ip

Quick Start 🚀

import express from "express";
import { getClientIp } from "get-client-ip";

const app = express();

// Middleware — auto-populates req.clientIp and req.clientIps
app.use(getClientIp);

app.get("/me", (req, res) => {
  res.json({ ip: req.clientIp, ips: req.clientIps });
});

// Or standalone — call directly in a specific route
app.get("/ip", (req, res) => {
  const ip = getClientIp(req);
  res.json({ ip });
});

app.listen(3000);

API Reference 📖

getClientIp(req, res?, next?): string | undefined

Extracts the client's IP address from an incoming request. Works both as a standalone function and as Express middleware. Returns string | undefined.

Side effects: Sets req.clientIp and req.clientIps on the request object when a valid IP is found. Throws if req is undefined.

TypeScript Augmentation

The package augments the Express Request type automatically:

// These properties are available after calling getClientIp
req.clientIp; // string | undefined — first valid IP
req.clientIps; // [string, ...string[]] | undefined — all valid IPs (non-empty array)

No manual type declarations are needed.

Header Priority 📋

Sources are checked in the following order. The first valid IP found is returned.

| Priority | Source | Description | | -------- | -------------------------- | -------------------------------------- | | 1 | req.ip | Express trust proxy setting | | 2 | Forwarded | RFC 7239 (parsed for for= directive) | | 3 | CF-Connecting-IP | Cloudflare | | 4 | True-Client-IP | Akamai / Cloudflare Enterprise | | 5 | Fastly-Client-IP | Fastly CDN | | 6 | X-Appengine-User-IP | Google App Engine | | 7 | CF-Pseudo-IPv4 | Cloudflare pseudo-IPv4 | | 8 | X-Client-IP | General proxy header | | 9 | X-Forwarded-For | De facto standard proxy header | | 10 | Forwarded-For | Variant of X-Forwarded-For | | 11 | X-Forwarded | Microsoft variant | | 12 | X-Real-IP | Nginx proxy header | | 13 | X-Cluster-Client-IP | Rackspace / Riverbed | | 14 | req.socket.remoteAddress | Direct connection fallback |

NestJS 🧩

import { Controller, Get, Req } from "@nestjs/common";
import type { Request } from "express";
import { getClientIp } from "get-client-ip";

@Controller()
export class AppController {
  @Get("ip")
  getIp(@Req() req: Request) {
    const ip = getClientIp(req);
    return { ip };
  }
}

Security 🛡️

Header trust warning: When req.ip is not populated, forwarding headers are used only when req.socket.remoteAddress appears to be from a local/private proxy range. Public socket peers skip header fallback to reduce spoofing risk.

In production behind a reverse proxy:

1. Configure Express's trust proxy setting so that req.ip is correctly populated
2. This ensures the function returns req.ip first and avoids fallback ambiguity
3. Without trust proxy, forwarding headers may still be ignored when the peer is public

CGNAT addresses: Addresses in the 100.64.0.0/10 range (RFC 6598) are treated as public, not trusted proxy addresses. Headers are not trusted when the socket peer is a CGNAT address. If your application is behind a load balancer (e.g., AWS ALB), configure Express's trust proxy setting so req.ip is populated correctly.

Credits 🙏

Inspired by Petar Bojinov's work on client IP detection.

Contributions 🤝

• Open an issue or feature request
• Submit a PR to improve the package
• Star the repo if you find it useful

Crafted carefully by WolfieLeader

This project is licensed under the MIT License.