get-client-ip

A Lightweight Utility for Extracting
the Real Client IP Address from
Incoming HTTP Requests

## About 📖 `get-client-ip` is a lightweight utility that extracts the real client IP address from an incoming HTTP request in Node.js. It supports common proxy headers (`x-forwarded-for`, `x-real-ip`, etc.) and works seamlessly as both: - a **standalone utility function**, and - **Express-compatible middleware**. It adds `req.clientIp` and `req.clientIps` to the request object when used as middleware — no setup required. ## Features 🌟 - 🌐 **Header-Aware Detection** – Parses standard and cloud-specific proxy headers. - 🧠 **Smart Parsing** – Handles multiple IPs, comma-separated values, and arrays. - 🧩 **Middleware-Compatible** – Use as drop-in Express/NestJS middleware. - 💪🏽 **Works in Standalone Mode** – Can be used as a simple function. - ⚙️ **Type-Safe & Cross-Compatible** – Fully written in TypeScript with native types. Works in both ESM and CommonJS runtimes. ## Installation 🔥 ```bash npm install get-client-ip@latest ``` > 💡 Works with `npm`, `pnpm`, and `yarn`. You can use it in dev dependencies since it's typically used only for local HTTPS. ## Usage 🪛 ### Express 📫 ```typescript import http from 'node:http'; import express from 'express'; import { getClientIp } from 'get-client-ip'; import { env } from './env'; function bootstrap() { const app = express(); app.use(express.json()); app.use(express.urlencoded({ extended: true })); // Standalone usage: app.get('/standalone-ip', (req, res) => { const ip = getClientIp(req); res.status(200).json({ ip }); }); // Middleware usage: app.get('/middleware-ip', getClientIp, (req, res) => { res.status(200).json({ ip: req.clientIp, ips: req.clientIps }); }); http.createServer(app).listen(env.PORT || 3000, () => { console.log(`🚀 Express server running on: http://localhost:${env.PORT || 3000}`); }); } bootstrap(); ``` ### NestJS 🪺 ```typescript import { Controller, Get, Req } from '@nestjs/common'; import type { Request } from 'express'; import { getClientIp } from 'get-client-ip'; @Controller('') export class PublicController { @Get('ip') getIp(@Req() req: Request) { const ip = getClientIp(req); return { ip }; } } ``` ## Headers ⛑️ The following headers are checked in order of precedence: ```typescript x-client-ip x-forwarded-for forwarded-for x-forwarded forwarded x-real-ip cf-connecting-ip true-client-ip x-cluster-client-ip fastly-client-ip x-appengine-user-ip cf-pseudo-ipv4 ``` It also falls back to: ```typescript req.ip; req.socket.remoteAddress; req.connection.remoteAddress; ``` ## Credit 💪🏽 We want to thank [Petar Bojinov](https://github.com/pbojinov) for the inspiration. ## Contributions 🤝 Want to contribute or suggest a feature? - Open an issue or feature request - Submit a PR to improve the packages or add new ones - Star ⭐ the repo if you like what you see ## License 📜 This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). Thank you!