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.

完整安装指南与集成提示词将在购买后解锁。