forwarded

library0.2.0jsnpmunverified

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.

http-networking

npm install forwarded

github ↗package ↗

INSTALL

IMPORT

SIG · FORWARDED

forwarded

http-networkingjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

forwarded

✓ const forwarded = require('forwarded')

✗ import forwarded from '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

✓ import forwarded from 'forwarded'

✗ import { forwarded } from 'forwarded'

The package exports a single function as its default export. Attempting to use named import will result in a TypeError.

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']

Debug

Known issues

gotchaVersion 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.

affects: >=0.2.0

gotchaThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: forwarded is not a function

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')

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.

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.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/jshttp/forwarded ↗

packagehttps://www.npmjs.com/package/forwarded ↗