follow-redirects

follow-redirects wraps Node.js’s native http and https modules so that request() and get() calls behave exactly like the built-ins, except that 3xx redirect chains are followed automatically instead of being surfaced to the caller as a response the app has to re-request itself. It exposes the final redirected URL on response.responseUrl, can optionally record the full chain of hops via trackRedirects, and strips sensitive headers like Authorization, Cookie, and Proxy-Authorization whenever a redirect crosses a host or protocol boundary, closing a class of credential-leak bugs that hand-rolled redirect-following code commonly misses.

Because it mirrors the native module APIs almost exactly, it slots underneath higher-level HTTP clients rather than being used directly by most application code — most notably it is the redirect engine inside axios, one of the most widely used HTTP clients in the Node ecosystem, which is reflected in its enormous weekly download count relative to its small, single-purpose codebase.

What You Get

• Drop-in http and https replacements with identical request()/get() signatures, so existing code needs no rewrite beyond the import
• Automatic following of 3xx redirect chains, with the final URL exposed on response.responseUrl
• Configurable maxRedirects and maxBodyLength guards that raise typed errors (ERR_FR_TOO_MANY_REDIRECTS, ERR_FR_MAX_BODY_LENGTH_EXCEEDED) instead of hanging or silently truncating
• Automatic stripping of sensitive headers (Authorization, Cookie, Proxy-Authorization, plus any caller-supplied sensitiveHeaders) when a redirect crosses hosts or protocols
• A beforeRedirect hook to inspect or rewrite outgoing options on each hop, or abort the request by throwing
• A wrap() function to layer redirect-following on top of custom http/https-shaped implementations, which is how caching or instrumented HTTP layers can add redirect support

Common Use Cases

• Powering the redirect-following logic inside higher-level HTTP clients (this is how axios follows redirects internally)
• Fetching URLs from user-submitted or third-party sources where the final destination after redirects is unknown and needs to be inspected before trusting the response
• Any server-side proxy or crawler that needs bounded, safe redirect-following without leaking auth headers to a different origin
• Replacing raw http.request/https.request calls in legacy code where redirects were previously handled manually with ad hoc loops

Under The Hood

Architecture The library centers on a single RedirectableRequest class that extends Node’s Writable stream and wraps a native http/https request object rather than reimplementing socket handling. Native response and lifecycle events (abort, aborted, connect, error, socket, timeout) are re-emitted onto the wrapping instance through a small event-handler table (index.js), so callers see a single consistent EventEmitter interface regardless of how many hops occur underneath. _processResponse inspects each native response for a redirect status code, applies _sanitizeOptions and the sensitive-header regex filter built from sensitiveHeaders, and either resolves the visible response or issues the next hop, tracking hop count in _redirectCount and, optionally, hop history in _redirects. Distinct error subclasses (InvalidUrlError, RedirectionError, TooManyRedirectsError, MaxBodyLengthExceededError, WriteAfterEndError) carry stable error codes so callers can branch on failure type rather than parsing messages. A top-level wrap() factory produces http/https-shaped module replacements bound to any underlying protocol implementation, which is what lets custom/cached transports gain redirect support without touching this internal logic.

Tech Stack Zero runtime dependencies — only Node’s own url, http, https, stream, and assert core modules are required, with debug wired in as an optional peer dependency purely for DEBUG=follow-redirects log output. The package ships as plain CommonJS (index.js, with http.js/https.js as one-line re-export shims for bundler aliasing) and declares engines.node >= 4.0, reflecting its role as low-level infrastructure that must run in whatever Node version its dependents target. Dev tooling is limited to what’s needed to test and lint: mocha + nyc for tests and coverage, eslint for linting, and express only as an in-process test server.

Code Quality Test coverage is extensive relative to the codebase size: a single 2,355-line test/test.js exercises over 100 cases covering redirect-count limits, body-length limits, cross-protocol redirects, method downgrades on 301/302/303, header sanitization across origins, the beforeRedirect hook, timeouts, and agent selection per protocol, run under nyc for coverage reporting. ESLint extends eslint:recommended with a substantial set of stylistic and best-practice rules enabled explicitly. CI (GitHub Actions) runs both lint and a test matrix spanning roughly twenty Node.js versions from 4.x through the current release, which is unusually broad and signals a deliberate commitment to long-tail compatibility for a package this deep in the dependency tree. Error handling is explicit throughout, using the typed error classes described above rather than generic thrown strings or swallowed exceptions.

What Makes It Unique The library’s core value isn’t a novel redirect algorithm — following 3xx chains is a well-understood problem — but the completeness of its safety handling: automatic, non-optional stripping of credential-bearing headers on cross-origin or cross-protocol hops is a real security property that many simpler or hand-rolled redirect-following implementations omit entirely, and the configurable maxRedirects/maxBodyLength guards with typed errors give callers a way to fail safely rather than hang. Its near-total API parity with Node’s native http/https modules, combined with the wrap() escape hatch for custom transports, is what has made it the de facto redirect layer beneath other popular HTTP clients rather than a library developers reach for directly.