get-client-ip

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 🔥

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 📫

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 💪🏽

We want to thank Petar Bojinov 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.

Thank you!