migration-guides.md

Migration guides

⭐ Switching from other HTTP request libraries to Got ⭐

Migrating from Request

You may think it's too hard to switch, but it's really not. 🦄

Let's take the very first example from Request's readme:

const request = require('request');

request('https://google.com', (error, response, body) => {
	console.log('error:', error); // Print the error if one occurred
	console.log('statusCode:', response && response.statusCode); // Print the response status code if a response was received
	console.log('body:', body); // Print the HTML for the Google homepage
});

With Got, it is:

const got = require('got');

(async () => {
	try {
		const response = await got('https://google.com');
		console.log('statusCode:', response.statusCode);
		console.log('body:', response.body);
	} catch (error) {
		console.log('error:', error);
	}
})();

Looks better now, huh? 😎

Common options

Both Request and Got accept http.request options.

These Got options are the same as with Request:

• url (+ we accept URL instances too!)
• body
• followRedirect
• encoding

So if you're familiar with them, you're good to go.

Oh, and one more thing... There's no time option. Assume it's always true.

Renamed options

Readability is very important to us, so we have different names for these options:

• qs → searchParams
• strictSSL → rejectUnauthorized
• gzip → decompress
• jar → cookieJar (accepts tough-cookie jar)

It's more clear, isn't it?

Changes in behavior

The timeout option has some extra features. You can set timeouts on particular events!

The searchParams option is always serialized using URLSearchParams unless it's a string.

There's no maxRedirects option. It's always set to 10.

To use streams, just call got.stream(url, options) or got(url, {stream: true, ...}).

Breaking changes

• The json option is not a boolean, it's an Object. It will be stringified and used as a body.
• No form option. You have to pass a form-data instance through the body option.
• No oauth/hawk/aws/httpSignature option. To sign requests, you need to create a custom instance.
• No agentClass/agentOptions/pool option.
• No forever option. You need to use forever-agent.
• No proxy option. You need to pass a custom agent.
• No baseUrl option. Instead, there is prefixUrl which appends a trailing slash if not present. It will be always prepended unless url is an instance of URL.
• No removeRefererHeader option. You can remove the referer header in a beforeRequest hook:

const gotInstance = got.extend({
	hooks: {
		beforeRequest: [
			options => {
				delete options.headers.referer;
			}
		]
	}
});

gotInstance(url, options);

• No jsonReviver/jsonReplacer option, but you can use hooks for that too:

const gotInstance = got.extend({
	hooks: {
		init: [
			options => {
				if (options.jsonReplacer && options.body) {
					options.body = JSON.stringify(options.body, options.jsonReplacer);
				}
			}
		],
		afterResponse: [
			response => {
				const options = response.request.gotOptions;
				if (options.jsonReviver && options.responseType === 'json') {
					options.responseType = '';
					response.body = JSON.parse(response.body, options.jsonReviver);
				}

				return response;
			}
		]
	}
});

gotInstance(url, options);

Hooks are powerful, aren't they? Read more to see what else you achieve using hooks.

More about streams

Let's take a quick look at another example from Request's readme:

http.createServer((request, response) => {
	if (request.url === '/doodle.png') {
		request.pipe(request('https://example.com/doodle.png')).pipe(response);
	}
});

The cool feature here is that Request can proxy headers with the stream, but Got can do that too:

const stream = require('stream');
const {promisify} = require('util');
const got = require('got');

const pipeline = promisify(stream.pipeline);

http.createServer(async (request, response) => {
	if (request.url === '/doodle.png') {
		// When someone makes a request to our server, we receive a body and some headers.
		// These are passed to Got. Got proxies received data to our server response,
		// so you don't have to do `response.writeHead(statusCode, headers)` and `response.end(body)`.
		// It's done automatically.
		await pipeline(
			got.stream('https://example.com/doodle.png'),
			response
		);
	}
});

Nothing has really changed. Just remember to use got.stream(url, options) or got(url, {stream: true, …}). That's it!

You're good to go!

Well, you have already come this far. Take a look at the documentation. It's worth the time to read it. There are some great tips. If something is unclear or doesn't work as it should, don't hesitate to open an issue.