Required dependencies

npm install @sindresorhus/is byte-counter cacheable-lookup cacheable-request chunk-data decompress-response http2-wrapper keyv lowercase-keys responselike type-fest uint8array-extras

No native build steps, pod installs, or Android linking required. This is pure Node.js ESM. Node.js 18+ is required (uses node:events addAbortListener, native AbortController, etc.).

Project setup

1. Copy source/ into your project, e.g. src/got/.
2. Ensure your tsconfig.json targets ESM and enables path resolution:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022",
    "strict": true
  }
}

3. Add "type": "module" to your package.json (Got is native ESM; no CJS export).
4. If using path aliases, map got to src/got/index.ts:

{
  "compilerOptions": {
    "paths": {
      "got": ["./src/got/index.ts"]
    }
  }
}

5. No environment variables are required by default. Optional: set up a CookieJar or custom cache adapter via Options.

Public API

got (default export)

import got from './src/got/index.js';
// got(url, options?) => RequestPromise<unknown>
// got.get / .post / .put / .patch / .delete / .head
// got.stream(url, options?) => Request (Duplex stream)
// got.paginate(url, options?) => AsyncIterableIterator<T>
// got.extend(options | Got) => Got

The pre-built Got instance. Use it directly for one-off requests or as the base for got.extend() to create scoped instances with shared defaults.

Options

import Options from './src/got/core/options.js';
// new Options(url?, optionsInit?, parent?)

A class that normalizes and merges all request options (URL, headers, retry, timeout, hooks, auth, proxy, etc.). Pass an OptionsInit plain object or compose from a parent Options instance. Use when building reusable option sets or custom Got instances via create().

create

import create from './src/got/create.js';
import type { InstanceDefaults } from './src/got/types.js';
// create(defaults: InstanceDefaults) => Got

Builds a fully functional Got instance from scratch. Use when you need a custom handler pipeline (handlers array), mutable defaults, or complete isolation from the default got instance.

calculateRetryDelay

import calculateRetryDelay from './src/got/core/calculate-retry-delay.js';
// calculateRetryDelay(retryObject: RetryObject) => number (ms)

Default exponential-backoff retry delay function. Override it via options.retry.calculateDelay to implement custom back-off strategies (e.g. honour Retry-After headers).

parseLinkHeader

import parseLinkHeader from './src/got/core/parse-link-header.js';
// parseLinkHeader(header: string) => Array<{url: string, rel: string, [key: string]: string}>

Parses RFC 5988 Link response headers into structured objects. Useful for pagination via Link: <next>; rel="next" without enabling the full pagination API.

Working examples

Scenario - Simple JSON GET request

A basic authenticated GET that parses a JSON response body with full TypeScript types.

import got from './src/got/index.js';

type Repo = { full_name: string; stargazers_count: number };

const repo = await got('https://api.github.com/repos/sindresorhus/got', {
  headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` },
}).json<Repo>();

console.log(repo.full_name, repo.stargazers_count);

Scenario - Scoped instance with shared base URL and retry config

Create a reusable API client that retries on 429/5xx, sets a base prefix, and attaches auth headers globally.

import got from './src/got/index.js';
import type { Delays } from './src/got/core/timed-out.js';
import type { RetryOptions } from './src/got/core/options.js';

const retry: RetryOptions = {
  limit: 3,
  statusCodes: [429, 500, 502, 503, 504],
  methods: ['GET', 'POST'],
};

const timeout: Delays = { request: 10_000 };

const api = got.extend({
  prefixUrl: 'https://api.example.com/v1',
  headers: { 'X-Api-Key': process.env.API_KEY ?? '' },
  retry,
  timeout,
});

const users = await api.get('users').json<{ id: string }[]>();
console.log(users);

Scenario - Streaming a large file download with progress

Use the stream API to pipe a large file to disk, tracking download progress.

import { createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import got from './src/got/index.js';

const download = got.stream('https://releases.ubuntu.com/22.04/ubuntu-22.04.3-live-server-amd64.iso');

download.on('downloadProgress', ({ transferred, total, percent }) => {
  process.stdout.write(`\rDownloaded ${(percent * 100).toFixed(1)}% (${transferred}/${total})`);
});

await pipeline(download, createWriteStream('/tmp/ubuntu.iso'));
console.log('\nDone.');

Scenario - Paginated API with got.paginate

Iterate through all pages of a paginated REST API without loading all results into memory.

import got from './src/got/index.js';

type Item = { id: number; name: string };

const allItems: Item[] = [];

for await (const item of got.paginate<Item>('https://api.example.com/items', {
  searchParams: { per_page: 100 },
  pagination: {
    transform: (response) => (response.body as unknown as Item[]),
    paginate: ({ response }) => {
      const link = response.headers['link'] ?? '';
      const next = link.match(/<([^>]+)>;\s*rel="next"/)?.[1];
      return next ? { url: next } : false;
    },
  },
})) {
  allItems.push(item);
}

console.log(`Fetched ${allItems.length} items`);

File walkthrough

• source/index.ts — Creates the default got instance using create() and re-exports the entire public surface.
• source/create.ts — Contains the create(defaults) factory; wires up HTTP method aliases, stream(), paginate(), and extend().
• source/types.ts — Defines InstanceDefaults, HandlerFunction, GotReturn, ExtendOptions, Got, GotPaginate, GotStream, GotRequestFunction, OptionsWithPagination, StreamOptions.
• source/as-promise/index.ts — asPromise<T>(): wraps a Request stream into a cancellable Promise with retry loop, redirect handling, and response body decoding.
• source/as-promise/types.ts — RequestPromise<T> (Promise + .json(), .text(), .buffer() helpers) and supporting types.
• source/core/index.ts — Request extends Node.js Duplex; full HTTP dispatch lifecycle, cookie handling, caching, timeout enforcement, redirect following.
• source/core/options.ts — Options class and all option normalization logic; exports OptionsInit, NormalizedOptions, RetryOptions, PaginationOptions, and helpers like isSameOrigin, applyUrlOverride.
• source/core/errors.ts — Typed error hierarchy: RequestError (base), HTTPError, TimeoutError, CacheError, ReadError, MaxRedirectsError, UploadError, RetryError, AbortError, ParseError.
• source/core/response.ts — Response/PlainResponse types, isResponseOk(), parseBody(), decodeUint8Array(), cacheDecodedBody().
• source/core/timed-out.ts — Attaches per-phase timeouts (connect, send, response, etc.) to a ClientRequest; exports Delays type.
• source/core/calculate-retry-delay.ts — Default exponential back-off with jitter; respects Retry-After headers.
• source/core/diagnostics-channel.ts — Publishes request lifecycle events to node:diagnostics_channel for APM/tracing.
• source/core/parse-link-header.ts — Lightweight RFC 5988 Link header parser used by the pagination engine.
• source/core/utils/ — Small focused utilities: timer (request phase timings), get-body-size, proxy-events, defer-to-connect, weakable-map, options-to-url, strip-url-auth, is-unix-socket-url, is-client-request, unhandle.

Common pitfalls and fixes

• CJS / require() fails at runtime — Got is native ESM only; add "type": "module" to package.json and use .js extensions in all imports.
• tsconfig moduleResolution must be NodeNext or Bundler — Classic node resolution cannot resolve the .js extension ESM imports; switch to "moduleResolution": "NodeNext".
• cacheable-request peer expects a specific keyv version — Pin keyv to the same major version required by cacheable-request (^4) to avoid duplicate keyv instances silently breaking cache.
• decompress-response not stripping content-encoding header — Occurs when options.decompress is false but you call .json(); set decompress: true (the default) or manually handle the raw buffer.
• Retry fires on POST/PATCH unexpectedly — Default retry.methods includes idempotent methods only; explicitly pass methods: ['GET'] if you want to restrict retry scope.
• got.paginate terminates early with false — Your pagination.paginate function must return false (not undefined) to signal the last page; returning undefined also stops iteration but is semantically ambiguous.

Vibe-coding prompt template

I have vendored the Got HTTP library source into `src/got/` in my project.
The integration guide is in `USAGE.md` (also in this context).
The upstream package is `user@example.com` by sindresorhus.

Please help me integrate it step-by-step:

1. Read `USAGE.md` and `src/got/index.ts` to understand the exported API.
2. Install all required dependencies listed in the "Required dependencies" section of USAGE.md.
3. Update my `tsconfig.json` and `package.json` as described in "Project setup".
4. Create a typed API client in `src/lib/http.ts` using `got.extend()` with:
   - A `prefixUrl` read from `process.env.API_BASE_URL`
   - An `Authorization` header from `process.env.API_TOKEN`
   - Retry limit of 3 on 5xx status codes
   - A 15-second request timeout
5. Add a helper function `fetchJson<T>(path: string, options?): Promise<T>` that wraps the client.
6. Show me a usage example for a POST request with a JSON body.
7. Show me how to handle `HTTPError` and `TimeoutError` from `src/got/core/errors.ts` distinctly.

Do not invent any APIs. Only use symbols visible in `src/got/index.ts` and `USAGE.md`.

License and credit

Got is released under the MIT License. See source/LICENSE if present, or refer to the upstream repository. Upstream npm package: got by Sindre Sorhus and contributors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.