HTTP X-Forwarded-For Header Parser

0.2.0 · maintenance · verified Tue Apr 21

The `forwarded` package is a minimalist Node.js utility designed to robustly parse the `X-Forwarded-For` HTTP header. It extracts a list of IP addresses from the request, including the direct socket address, and returns them in reverse proxy order, where index `0` represents the immediate client (the socket address) and the last index is the furthest origin (typically the end-user's IP). This is crucial for applications running behind proxies or load balancers, where `req.ip` or `req.connection.remoteAddress` would only reflect the proxy's IP. The current stable version is 0.2.0, released in May 2021. Being part of the `jshttp` organization, `forwarded` adheres to a philosophy of creating small, single-purpose, and highly performant modules. Its release cadence is exceptionally slow, with only four releases since its initial launch in 2014, which underscores its stability and the mature nature of its functionality. It has no external runtime dependencies, making it a lightweight and reliable choice for foundational HTTP parsing tasks.

Common errors

```
TypeError: forwarded is not a function
```
cause Attempting to use `import { forwarded } from 'forwarded'` (named import) when the package exports a default function. Or, an issue with CommonJS/ESM interop where a bundler or Node.js isn't correctly resolving the default export.

fix For CommonJS, use `const forwarded = require('forwarded')`. For ESM, use `import forwarded from 'forwarded'` to correctly import the default export.
```
TypeError: Cannot read properties of undefined (reading 'headers')
```
cause The `req` object passed to `forwarded` is either `null`, `undefined`, or does not conform to the expected Node.js `IncomingMessage` structure (specifically lacking a `headers` property).

fix Ensure the argument passed to `forwarded()` is a valid Node.js `IncomingMessage` object or a compatible mock object that includes a `headers` property (even if empty) and a `socket.remoteAddress` property.
```
My application is reporting the proxy's IP, not the client's IP.
```
cause This is often a misconfiguration of proxy servers not correctly setting the `X-Forwarded-For` header, or the application not correctly parsing it.

fix Verify that your proxy or load balancer is correctly forwarding the `X-Forwarded-For` header to your Node.js application. Also, ensure you are using the last element of the array returned by `forwarded(req)` to get the furthest client IP.

Warnings

gotcha Version 0.2.0 (released May 2021) changed its internal implementation to use `req.socket` instead of the deprecated `req.connection` for retrieving the remote address. While this improves compatibility with newer Node.js versions, applications that might have relied on or manipulated `req.connection` in highly specific ways might observe subtle behavioral differences, although the public API of `forwarded` itself remains unchanged.
Fix: Ensure your Node.js environment is up-to-date and avoid relying on deprecated `req.connection` properties directly in your application code. The `forwarded` package transparently handles the correct property access.
gotcha The package returns IP addresses in 'reverse proxy order'. This means `addresses[0]` is the most immediate connection (your server's socket) and the last element is the furthest client (the original end-user). Misinterpreting this order can lead to incorrect client IP identification.
Fix: Always remember that the array returned by `forwarded(req)` is in reverse order of proxies. If you need the original client's IP, it will typically be the last element of the array.

Install

npm install forwarded npm
yarn add forwarded yarn
pnpm add forwarded pnpm

Imports

forwarded
wrong:
```
import forwarded from 'forwarded'
```
correct:
```
const forwarded = require('forwarded')
```
Primary usage shown in documentation is CommonJS. While Node.js ESM can typically import CJS default exports, explicit `require` is the documented approach.
forwarded
wrong:
```
import { forwarded } from 'forwarded'
```
correct:
```
import forwarded from 'forwarded'
```
The package exports a single function as its default export. Attempting to use named import will result in a TypeError.

Quickstart

This example demonstrates how to use the `forwarded` function with a mock HTTP request object, showing how it parses the `X-Forwarded-For` header and includes the socket's remote address in the correct reverse proxy order, even when the header is absent.

import forwarded from 'forwarded';

const mockRequest = {
  headers: {
    'x-forwarded-for': '203.0.113.195, 70.41.3.18, 150.172.238.1'
  },
  socket: {
    remoteAddress: '192.0.2.4'
  }
};

const addresses = forwarded(mockRequest);

console.log('Parsed addresses (reverse proxy order):', addresses);
// Expected output: ['192.0.2.4', '150.172.238.1', '70.41.3.18', '203.0.113.195']

const mockRequestWithoutHeader = {
  headers: {},
  socket: {
    remoteAddress: '10.0.0.1'
  }
};

const addressesNoHeader = forwarded(mockRequestWithoutHeader);
console.log('Addresses without X-Forwarded-For:', addressesNoHeader);
// Expected output: ['10.0.0.1']

view raw JSON →