Request

Migration guides

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:

import request from 'request';

request('https://google.com', (error, response, body) => {
	console.log('error:', error);
	console.log('statusCode:', response && response.statusCode);
	console.log('body:', body);
});

With Got, it is:

import got from 'got';

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

These Got options are the same as with Request:

The time option does not exist, assume it's always true.

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

Renamed options

Note:

Got stores HTTPS options inside https. Some of them have been renamed. Read more.

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)
jsonReviver → parseJson
jsonReplacer → stringifyJson

Changes in behavior

The agent option is now an object with http, https and http2 properties.
The timeout option is now an object. You can set timeouts on particular events!
The searchParams option is always serialized using URLSearchParams.
In order to pass a custom query string, provide it with the url option.
got('https://example.com', {searchParams: {test: ''}}) → https://example.com/?test=
got('https://example.com/?test') → https://example.com/?test
To use streams, call got.stream(url, options).

Breaking changes

The json option is not a boolean, it's an object. It will be stringified and used as a body.
The form option is an object and will be used as application/x-www-form-urlencoded body.
All headers are converted to lowercase.
According to the spec, the headers are case-insensitive.
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 pass an agent with keepAlive option set to true.
No proxy option. You need to pass a custom agent.
No auth option.
You need to use username / password instead or set the authorization header manually.
No baseUrl option.
Instead, there is prefixUrl which appends a trailing slash if not present.
No removeRefererHeader option.
You can remove the referer header in a beforeRequest hook.
No followAllRedirects option.
copyPipedHeaders defaults to false.
Piped request headers are no longer copied automatically. Opt in with copyPipedHeaders: true for proxy scenarios.
With copyPipedHeaders: true, explicitly set headers win over piped headers.
Piped headers only fill headers that were not explicitly set.

Hooks are very powerful. 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((serverRequest, serverResponse) => {
	if (serverRequest.url === '/doodle.png') {
		serverRequest.pipe(request('https://example.com/doodle.png')).pipe(serverResponse);
	}
});

Request can proxy headers with the stream. Got can do that too, but it is opt-in:

import {pipeline as streamPipeline} from 'node:stream/promises';
import got from 'got';

const server = http.createServer(async (serverRequest, serverResponse) => {
	if (serverRequest.url === '/doodle.png') {
		await streamPipeline(
			serverRequest,
			got.stream('https://example.com/doodle.png', {copyPipedHeaders: true}),
			serverResponse
		);
	}
});

server.listen(8080);

In terms of stream usage, nothing has really changed, but header proxying is opt-in via copyPipedHeaders: true.

Convenience methods

If you were using request.get, request.post, and so on - you can do the same with Got.
The request.defaults({…}) method has been renamed. You can do the same with got.extend({…}).
There is no request.cookie() nor request.jar(). You have to use tough-cookie directly.

You're good to go!

Well, you have already come this far :tada:
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.