{"id":16036,"library":"forwarded","title":"HTTP X-Forwarded-For Header Parser","description":"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.","status":"maintenance","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/jshttp/forwarded","tags":["javascript","x-forwarded-for","http","req"],"install":[{"cmd":"npm install forwarded","lang":"bash","label":"npm"},{"cmd":"yarn add forwarded","lang":"bash","label":"yarn"},{"cmd":"pnpm add forwarded","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary usage shown in documentation is CommonJS. While Node.js ESM can typically import CJS default exports, explicit `require` is the documented approach.","wrong":"import forwarded from 'forwarded'","symbol":"forwarded","correct":"const forwarded = require('forwarded')"},{"note":"The package exports a single function as its default export. Attempting to use named import will result in a TypeError.","wrong":"import { forwarded } from 'forwarded'","symbol":"forwarded","correct":"import forwarded from 'forwarded'"}],"quickstart":{"code":"import forwarded from 'forwarded';\n\nconst mockRequest = {\n  headers: {\n    'x-forwarded-for': '203.0.113.195, 70.41.3.18, 150.172.238.1'\n  },\n  socket: {\n    remoteAddress: '192.0.2.4'\n  }\n};\n\nconst addresses = forwarded(mockRequest);\n\nconsole.log('Parsed addresses (reverse proxy order):', addresses);\n// Expected output: ['192.0.2.4', '150.172.238.1', '70.41.3.18', '203.0.113.195']\n\nconst mockRequestWithoutHeader = {\n  headers: {},\n  socket: {\n    remoteAddress: '10.0.0.1'\n  }\n};\n\nconst addressesNoHeader = forwarded(mockRequestWithoutHeader);\nconsole.log('Addresses without X-Forwarded-For:', addressesNoHeader);\n// Expected output: ['10.0.0.1']","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const forwarded = require('forwarded')`. For ESM, use `import forwarded from 'forwarded'` to correctly import the default export.","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.","error":"TypeError: forwarded is not a function"},{"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.","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).","error":"TypeError: Cannot read properties of undefined (reading 'headers')"},{"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.","cause":"This is often a misconfiguration of proxy servers not correctly setting the `X-Forwarded-For` header, or the application not correctly parsing it.","error":"My application is reporting the proxy's IP, not the client's IP."}],"ecosystem":"npm"}