got's own front page tells you to use a different library instead

The front page opens by recommending a different library from the same author

This is the first substantive paragraph in the readme, and it is an argument against using the thing you just arrived at.

It says you probably want a different library, by the same people. The reasons given are that it is smaller, that it works in the browser too, and that it is more stable because it is built on the platform's own fetch interface. For simple needs it names a third option.

All three are by the same author, and one of the three is a direct competitor to this one. A maintainer telling you that a smaller sibling is more stable than their own larger project is an unusual thing to publish, and it tells you two useful things.

First, the comparison table further down the page is not advocacy. The same table marks this library as having no browser support while all four competitors have it, and marks pagination as something only this one does. Where the table favours competitors, it says so. That is a comparison you can trust.

Second, the advice is specific. Fetch-based libraries will be more stable on this author's own assessment, which for a library sitting on a platform interface rather than a Node-specific one is a reasonable claim rather than modesty.

So the consequence is to read the front page as doing triage. If your use needs pagination, caching or streaming, stay. If it does not, the author has told you which of his packages to install instead.

Failed requests are retried by default, and turning that off is a documented step

This is a default that surprises people, and the documentation leads with it rather than burying it.

The documentation section opens by stating that retries happen on failure by default, and that to disable this the retry limit option is set to zero. That sentence is the first thing in the documentation list, before the main API.

Why this matters is that retrying is only safe for requests where doing it twice changes nothing. A retrieval is fine. A submission may not be, and a payment or a created resource can be duplicated by the client's own retry logic rather than by anything the server did wrong.

The README names the option, options.retry.limit, and links to the retry documentation for the details of which requests are retried.

So the consequence is that adopting this library without reading that line can change the behaviour of your application in a way that only shows up under failure. Set it per call site on the first day rather than after your first duplicate.

There is no CommonJS entry point and the front page asks you not to ask about it

The install section carries a warning that is worth reading in full, because it includes an instruction about what not to do afterwards.

The package is native ES modules and no longer provides a CommonJS export. If your project uses CommonJS, the front page says you will have to convert to ESM, and links a guide for doing it.

Then the second half of the warning: do not open issues for questions regarding CommonJS or ES modules.

That is a maintainer drawing a line, and it is a reasonable one given how many such reports a package this widely used receives. It also tells you the migration cost is on you.

The Node version floor makes that harder. The manifest requires Node 22 or newer. So the choice is not between two module systems, it is between modernising your module setup and modernising your runtime at the same time.

The older major version is closed off too. The front page states that the eleventh major version is no longer maintained and that no backport requests will be accepted.

So there are three separate closures in this one section: no CommonJS, no issues about it, and no backports to the previous major line.

The consequence is that this library now requires a modern runtime and a modern module setup, and if you are on an older codebase it is a migration project rather than an install.

Server-side request forgery protection is a separate plugin, not a feature

Among the plugins listed on the front page there is one whose description is worth reading twice.

The others wrap this client for a specific service or purpose: signed AWS request handling, a GitHub convenience wrapper, a GitLab wrapper, a GraphQL query interface that parses queries rather than treating them as strings, a fetch-shaped interface, a scraper-oriented wrapper.

The seventh is described as a wrapper to protect server-side requests against server-side request forgery attacks.

The feature list shown on the front page does not include address filtering or allow-listing, and this plugin is offered as the way to add it.

This matters more here than in most libraries because one of the listed use cases for the scraper-oriented wrapper is fetching arbitrary pages on a server's behalf. That is exactly the pattern where a URL comes from user input and the server fetches it, which is the shape of the vulnerability.

So the consequence is that if you accept URLs from users and fetch them server-side with this library, you need that plugin or an equivalent allow-list, and the front page does not flag that as a default-on protection because it is not one.

Migration guides exist for three different starting points, one of them now unmaintained

The documentation includes guides for coming to this library from three places, and the framing tells you what the author considers the alternatives to be.

There is a guide for migrating from the older request library, one for Axios, and one for Node.js.

Three guides means three distinct populations this library wants to serve: people on the older community-maintained request package, people on the most popular promise-based client, and people who have no client at all beyond what the platform provides.

The note attached to the first guide is that the library being migrated from is unmaintained. That is stated as a fact with a link to its own tracker, which is both a reason to leave and a reason to be sceptical of a migration guide written partly to help people escape an abandoned dependency.

What none of the guides says is the reverse direction. There is no guidance here for someone deciding to leave this library, even though the opening paragraph recommends one of the alternatives. That asymmetry is honest and worth noticing: the author is actively helping people in, not out.

So the consequence is that the migration guides are a reasonable evaluation tool. Reading the Axios one tells you what this library thinks Axios users will miss, which is a compact statement of its own feature set.

The published package is one directory of compiled files with a single entry point

The manifest describes a deliberately narrow distribution, and it explains what you actually install.

There is a single entry point in the exports map, pointing at a type definition file and a compiled file in the same directory. There is no second entry point and no conditional export for a CommonJS consumer, which is the mechanical fact behind the warning in the install section.

The published files list is a single path, the compiled source directory. So the package is the build output and nothing else, with no sources and no test files in the tarball.

The package is also declared free of side effects, which lets a bundler drop it entirely if nothing is imported from it.

On the source side, the build is a single compiler invocation after deleting the output directory, and it runs automatically on install through the prepare script. Type checking is part of the test command rather than a separate step, running before the test runner alongside a linter.

So the consequence is that this is a compiled, single-entry, dependency-light package with no CommonJS path. That is a clean shape for a modern bundler and an awkward one for an older application.

The retry, pagination and caching features are the reason to be here at all

The comparison table is the clearest statement of what this library does that the alternatives do not, and it is a short list.

Streaming responses: this library and superagent have it, node-fetch has it only on Node, and ky and axios do not have it.

Pagination: this library has it, and none of the four competitors do.

Caching that follows the HTTP specification: this library lists RFC 7234 compliant caching among its features.

HTTP/2: this library and ky have it, node-fetch and axios do not, and superagent does with a caveat marker in the table.

Request aborting: all four have it.

Promise interface: all four have it.

So three features are genuinely differentiating and the rest is table stakes. If you are choosing between these libraries and you do not need pagination, caching, streaming, HTTP/2 or Unix sockets, the table says you are choosing on price, size and module format.

There is also a Unix domain socket option in the feature list, which matters if you are talking to a local service rather than a network one.

The JSON mode is the shape most people start from:

import got from 'got';

const {data} = await got.post('https://httpbin.org/anything', {
	json: {
		hello: 'world'
	}
}).json();

So the consequence is to identify which of those three you actually need before you start comparing. It is a much shorter conversation than a feature-by-feature one.

Editorial conclusion

This is the right tool when you specifically need the features it has that the fetch-based alternatives do not: automatic pagination over a listing endpoint, response caching that follows the HTTP specification, streaming responses, or Unix domain sockets. If you do not need one of those, the author is telling you plainly that a smaller library will serve you better, and he is the person who knows. Two things to check before you adopt it. Whether retries are acceptable in your request pattern, since they are on by default and you have to turn them off explicitly. And whether your application can be ES modules, because the package no longer ships a CommonJS entry point at all and the front page says not to open issues about it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sindresorhus/got on GitHub