get-client-ip

get-client-ip

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

Why get-client-ip? 🤔

• 🌐 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.

Installation 🔥

npm install get-client-ip@latest
# or
yarn add get-client-ip@latest
# or
pnpm install get-client-ip@latest
# or
bun add get-client-ip@latest

Usage 🪛

Express 📫

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 🪺

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:

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:

req.ip;
req.socket.remoteAddress;
req.connection.remoteAddress;

Credit 💪🏽

Huge credit to Petar Bojinov for the inspiration.

Contributions 🤝

Want to contribute or suggest a feature or improvement?

• 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

⚒️ Crafted carefully by WolfieLeader

This project is licensed under the MIT License.

Thank you!