follow-redirects

What is follow-redirects?

The follow-redirects npm package is a drop-in replacement for Node.js' native http and https modules that automatically follows HTTP(S) redirects. It provides an easy way to make HTTP(S) requests without having to manually handle redirection logic.

What are follow-redirects's main functionalities?

HTTP/HTTPS request with automatic redirection

This code demonstrates how to make a simple HTTP GET request that automatically follows redirects using the follow-redirects package.

const http = require('follow-redirects').http;

http.get('http://example.com', (response) => {
  response.on('data', (chunk) => {
    console.log(chunk.toString());
  });
}).on('error', (err) => {
  console.error(err);
});

Customizing redirect options

This code snippet shows how to customize the behavior of follow-redirects by setting the maximum number of redirects to follow and adding a hook to log the URL before redirecting.

const https = require('follow-redirects').https;

const options = {
  maxRedirects: 10,
  beforeRedirect: (options, { headers }) => {
    console.log(`Redirecting to: ${options.hostname}${options.path}`);
  }
};

https.get('https://example.com', options, (response) => {
  // Handle response
}).on('error', (err) => {
  console.error(err);
});

Streaming response data

This example demonstrates how to stream data from an HTTP GET request to a file, which is useful for downloading files while following redirects.

const http = require('follow-redirects').http;
const fs = require('fs');

const file = fs.createWriteStream('downloaded_file.txt');

http.get('http://example.com/file', (response) => {
  response.pipe(file);
}).on('error', (err) => {
  console.error(err);
});

Other packages similar to follow-redirects

axios

Axios is a promise-based HTTP client for the browser and Node.js that supports automatic redirection. It provides a more feature-rich API compared to follow-redirects, including interceptors, request cancellation, and protection against XSRF.

request

Request is a simplified HTTP request client that supports redirection by default. It is no longer maintained, but it was once a popular choice for making HTTP requests in Node.js. It offered a higher-level API with convenience methods and support for forms and multipart file uploads.

got

Got is a human-friendly and powerful HTTP request library for Node.js. It handles redirections by default and provides a wide range of options for customization, retries, streams, and more. It is designed to be a more modern and feature-rich alternative to other HTTP request libraries.

node-fetch

Node-fetch is a light-weight module that brings the Fetch API to Node.js. It follows redirects by default and aims to provide a consistent API with the browser's fetch function. It is a good choice for those who prefer the Fetch API's promise-based syntax.

README

Follow Redirects

Drop-in replacement for Nodes http and https that automatically follows redirects.

follow-redirects provides request and get methods that behave identically to those found on the native http and https modules, with the exception that they will seamlessly follow redirects.

var http = require('follow-redirects').http;
var https = require('follow-redirects').https;

http.get('http://bit.ly/900913', function (response) {
  response.on('data', function (chunk) {
    console.log(chunk);
  });
}).on('error', function (err) {
  console.error(err);
});

You can inspect the final redirected URL through the responseUrl property on the response. If no redirection happened, responseUrl is the original request URL.

https.request({
  host: 'bitly.com',
  path: '/UHfDGO',
}, function (response) {
  console.log(response.responseUrl);
  // 'http://duckduckgo.com/robots.txt'
});

Options

Global options

Global options are set directly on the follow-redirects module:

var followRedirects = require('follow-redirects');
followRedirects.maxRedirects = 10;
followRedirects.maxBodyLength = 20 * 1024 * 1024; // 20 MB

The following global options are supported:

• maxRedirects (default: 21) – sets the maximum number of allowed redirects; if exceeded, an error will be emitted.

• maxBodyLength (default: 10MB) – sets the maximum size of the request body; if exceeded, an error will be emitted.

Per-request options

Per-request options are set by passing an options object:

var url = require('url');
var followRedirects = require('follow-redirects');

var options = url.parse('http://bit.ly/900913');
options.maxRedirects = 10;
http.request(options);

In addition to the standard HTTP and HTTPS options, the following per-request options are supported:

• followRedirects (default: true) – whether redirects should be followed.

• maxRedirects (default: 21) – sets the maximum number of allowed redirects; if exceeded, an error will be emitted.

• maxBodyLength (default: 10MB) – sets the maximum size of the request body; if exceeded, an error will be emitted.

• agents (default: undefined) – sets the agent option per protocol, since HTTP and HTTPS use different agents. Example value: { http: new http.Agent(), https: new https.Agent() }

• trackRedirects (default: false) – whether to store the redirected response details into the redirects array on the response object.

Advanced usage

By default, follow-redirects will use the Node.js default implementations of http and https. To enable features such as caching and/or intermediate request tracking, you might instead want to wrap follow-redirects around custom protocol implementations:

var followRedirects = require('follow-redirects').wrap({
  http: require('your-custom-http'),
  https: require('your-custom-https'),
});

Such custom protocols only need an implementation of the request method.

Browserify Usage

Due to the way XMLHttpRequest works, the browserify versions of http and https already follow redirects. If you are only targeting the browser, then this library has little value for you. If you want to write cross platform code for node and the browser, follow-redirects provides a great solution for making the native node modules behave the same as they do in browserified builds in the browser. To avoid bundling unnecessary code you should tell browserify to swap out follow-redirects with the standard modules when bundling. To make this easier, you need to change how you require the modules:

var http = require('follow-redirects/http');
var https = require('follow-redirects/https');

You can then replace follow-redirects in your browserify configuration like so:

"browser": {
  "follow-redirects/http"  : "http",
  "follow-redirects/https" : "https"
}

The browserify-http module has not kept pace with node development, and no long behaves identically to the native module when running in the browser. If you are experiencing problems, you may want to check out browserify-http-2. It is more actively maintained and attempts to address a few of the shortcomings of browserify-http. In that case, your browserify config should look something like this:

"browser": {
  "follow-redirects/http"  : "browserify-http-2/http",
  "follow-redirects/https" : "browserify-http-2/https"
}

Contributing

Pull Requests are always welcome. Please file an issue detailing your proposal before you invest your valuable time. Additional features and bug fixes should be accompanied by tests. You can run the test suite locally with a simple npm test command.

Debug Logging

follow-redirects uses the excellent debug for logging. To turn on logging set the environment variable DEBUG=follow-redirects for debug output from just this module. When running the test suite it is sometimes advantageous to set DEBUG=* to see output from the express server as well.

Authors

• Olivier Lalonde ([e-mail])
• James Talmage ([e-mail])
• Ruben Verborgh

License

MIT: http://olalonde.mit-license.org