got

Got is one of the most widely depended-on HTTP request libraries in the Node.js ecosystem, used by tens of thousands of packages and millions of repositories. It wraps Node’s low-level http/https modules in a promise-first API while exposing the full power of streams underneath, so simple JSON requests stay one-liners and advanced use cases (proxying, unix sockets, HTTP/2) remain fully reachable.

What sets Got apart from lighter alternatives like node-fetch or ky is its breadth of built-in request-lifecycle features: automatic retries with configurable backoff, RFC 7234-compliant HTTP caching, a hooks system for intercepting every stage of a request (init, beforeRequest, beforeRedirect, afterResponse, beforeRetry, beforeError), a pagination API for walking paginated REST endpoints, and errors that carry structured metadata (response, request, timings, retry count) instead of opaque exceptions.

The library is maintained by Sindre Sorhus and a team of active contributors, ships native ESM-only (no CommonJS export in current major versions), and requires Node.js 22+. It’s commonly reached for when a project needs more control and resilience than fetch offers server-side — advanced timeout phases, cookie jars, and instance-level custom defaults are all first-class.

What You Get

• A promise API (await got(url)) plus a full Stream API for piping large request/response bodies
• Automatic retry-on-failure with configurable retry limits and backoff, on by default
• RFC 7234-compliant HTTP caching via the cacheable-request/keyv stack, with pluggable storage adapters
• A hooks system covering init, beforeRequest, beforeRedirect, afterResponse, beforeRetry, beforeError, and afterRequest for intercepting any stage of the request lifecycle
• A pagination API for iterating paginated REST APIs without hand-rolled loop logic
• Structured errors (RequestError, HTTPError, TimeoutError, MaxRedirectsError, CacheError, ParseError) carrying response, request, and timing metadata
• Advanced multi-phase timeout handling, response timings, and diagnostics-channel integration for observability
• Out-of-the-box cookie jar support, gzip/brotli/zstd decompression, and Unix Domain Socket requests

Common Use Cases

• Calling third-party REST APIs from a Node.js backend where retries and structured errors matter more than bundle size
• Building typed API wrapper packages (the README lists gh-got, gl-got, got4aws as examples of this exact pattern)
• Scraping or crawling workloads that need caching, redirect control, and fine-grained timeout tuning
• Streaming large file downloads or uploads through Node without buffering the whole payload in memory
• Server-side integrations that need to walk paginated API responses automatically via the pagination API

Under The Hood

Architecture

Got is organized as a layered core: source/core/index.ts defines a Request class that extends Node’s Duplex stream and owns the entire request lifecycle (URL/option normalization, redirect following, retry scheduling, response decoding), while source/core/options.ts (nearly 3,700 lines) implements a dedicated Options class with getter/setter-based normalization, merging, and validation so that option objects passed by callers are never trusted as-is. source/create.ts builds the public got function and its .extend()/instance mechanism on top of that core, and source/index.ts re-exports the assembled surface (Options, Response, Request, error classes, diagnostics-channel helpers) as the package entry point. Hooks are threaded through as an explicit array executed at named lifecycle points rather than a generic event-emitter, which keeps ordering and error propagation predictable; a change to the core Request class’s redirect/retry logic would ripple through streaming, caching, and pagination simultaneously since they all sit on the same request object.

Tech Stack

Got is TypeScript-only, ESM-only ("type": "module"), targets Node.js 22+, and ships compiled output (dist/source) built via tsc. Runtime dependencies are narrowly scoped single-purpose packages, most by the same maintainer: @sindresorhus/is for type checks, cacheable-request/keyv for the RFC 7234 cache layer, decompress-response for transparent gzip/brotli/zstd handling, responselike and lowercase-keys for response normalization, type-fest for advanced TypeScript types, and uint8array-extras/byte-counter/chunk-data for buffer and stream utilities. There is no bundler in the dependency chain — the package ships plain compiled JS with type declarations, and consumers import it directly.

Code Quality

The project has an extensive test suite (dozens of files under test/, covering redirects, retries, caching, cookies, DNS caching, hooks, streams, and error paths individually) run with ava, type-checked separately via tsc --noEmit, linted with xo (an opinionated ESLint preset with project-specific rule overrides), and measured for coverage with c8. CI (GitHub Actions) runs the full test/lint/typecheck suite across Node 22, 24, and 26 on every push and pull request, which is a strong continuous-compatibility signal for a library targeting a fast-moving Node.js version range.

What Makes It Unique

Most competing HTTP clients pick one of “minimal and fetch-like” (ky, node-fetch) or “batteries-included but browser-first” (axios); Got instead commits fully to the Node.js server environment and exposes capabilities that only make sense there — Unix Domain Socket requests, advanced multi-phase timeout breakdowns, and RFC 7234-correct caching semantics rather than a simple in-memory cache. Its pagination API and structured hook lifecycle are also comparatively rare: most alternatives leave both to userland wrapper code, whereas Got treats them as first-class, documented parts of the public API.