request-ip

Use getClientIp(req) to extract the client's IP address from a request object. The function inspects various headers and connection properties in a specific order of precedence to find a valid IP address.

It checks the following headers (in order):

1. x-client-ip
2. x-forwarded-for (parsed via getClientIpFromXForwardedFor)
3. cf-connecting-ip (Cloudflare)
4. fastly-client-ip (Fastly)
5. true-client-ip
6. x-real-ip
7. x-cluster-client-ip
8. x-forwarded
9. forwarded-for
10. forwarded
11. x-appengine-user-ip (Google App Engine)
12. Cf-Pseudo-IPv4 (Cloudflare)

If no valid header is found, it falls back to checking connection properties like req.connection.remoteAddress, req.socket.remoteAddress, req.info.remoteAddress, or req.requestContext.identity.sourceIp.

const { getClientIp } = require('request-ip');

// Example usage in an Express-like environment
app.get('/', (req, res) => {
  const ip = getClientIp(req);
  console.log('Client IP:', ip);
  res.send(`Your IP is ${ip}`);
});

Use getClientIp(req) to extract the originating client's IP address from a request object. The function implements a priority-based search through various HTTP headers used by different cloud providers and proxies, including:

• x-client-ip (Amazon EC2, Heroku)
• x-forwarded-for (AWS ELB, proxies)
• cf-connecting-ip (Cloudflare)
• do-connecting-ip (DigitalOcean)
• fastly-client-ip (Fastly, Firebase)
• true-client-ip (Akamai, Cloudflare)
• x-real-ip (Nginx)
• x-cluster-client-ip (Rackspace, Riverbed)
• x-appengine-user-ip (Google Cloud App Engine)
• Cf-Pseudo-IPv4 (Cloudflare fallback)

It also checks remote address properties on req.connection, req.socket, req.info, and req.requestContext.identity.sourceIp (AWS API Gateway + Lambda). For Fastify users, it can recursively call itself on req.raw.

Returns the IP address as a string if found, or null if the IP cannot be determined.

const { getClientIp } = require('request-ip');

// Example usage in an Express-like environment
function handleRequest(req, res) {
    const ip = getClientIp(req);
    console.log(`Client IP: ${ip}`);
    res.send(`Your IP is ${ip}`);
}

The mw(options) function returns a middleware function that augments the request object with the detected client IP address.

Configuration

Pass an options object to mw():

• options.attributeName (string, optional): The name of the property to add to the req object. Defaults to 'clientIp'.

Behavior

The middleware calculates the IP using getClientIp(req) and defines it as a getter on the request object using Object.defineProperty. This ensures the property is configurable: true.

Example

const express = require('express');
const { mw } = require('request-ip');

const app = express();

// Use default attribute name 'clientIp'
app.use(mw());

// Or use a custom attribute name
app.use(mw({ attributeName: 'ipAddress' }));

app.get('/', (req, res) => {
    // Access via the default name
    console.log(req.clientIp);
    
    // Access via custom name if configured
    // console.log(req.ipAddress);
    
    res.send('IP logged');
});

const { mw } = require('request-ip');

// Standard Express middleware usage
app.use(mw());

// Custom attribute name usage
app.use(mw({ attributeName: 'myCustomIpField' }));

The mw(options) function returns a middleware function that attaches the detected client IP to the req object.

Options

• attributeName (string): The name of the property to attach to the req object. Defaults to 'clientIp'.

If options is provided but is not an object, it throws a TypeError.

Usage

const requestIp = require('request-ip');
const express = require('express');
const app = express();

// Use default attribute name 'clientIp'
app.use(requestIp.mw());

// Or use a custom attribute name
app.use(requestIp.mw({ attributeName: 'ip' }));

app.get('/', (req, res) => {
  // Access the IP via the attribute name defined in middleware
  const ip = req.clientIp;
  res.send(ip);
});

const requestIp = require('request-ip');
const express = require('express');
const app = express();

app.use(requestIp.mw({ attributeName: 'clientIp' }));

app.get('/', (req, res) => {
  const ip = req.clientIp;
  res.send(ip);
});