npm · #3791 most downloaded on npm

ky

2.1.029M downloads/mosindresorhus/ky ↗New releases in your daily digest, changelog included.

Tiny and elegant HTTP client based on the Fetch API

Last release 1 months ago
28 Aug 2026
Release timing varies
gaps range from 8 days to 5 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
10 years old
100 releases · first in 2016

Release timeline

100 releases since 2016

2016201820202022

Releases

2.1.028 Aug 2026
Add QUERY method support ( #873 ) 6edddd9
Improvements

Add QUERY method support (#873) 6edddd9

Allow parseJson to handle empty bodies (#877) 294fe63

Reject malformed HTTP URLs with baseUrl be60db5

Improve Retry-After handling (#874) 3419113

Harden retry c426f19

Fixes

Fix progress callbacks for empty request and response bodies (#881) 99644d0

Fix signal replacement when extending instances (#880) 0bda554

Fix extend() dropping numeric retry limit when merging with an object (#867) 06375ef

Fix handling of Safari errors with domains 61d6d66

v2.0.2...v2.1.0

One column per quarter.

2.0.221 Apr 2026

Fix init hook URLSearchParams deletions add0703

Fix init hook URLSearchParams deletions add0703
Fix tuple searchParams mutations leaking across init-hook requests (#861) 346f898

v2.0.1...v2.0.2

Open source →

2.0.114 Apr 2026

Improve compatibility with custom fetch implementations ( #858 ) 2971991

Improve compatibility with custom fetch implementations (#858) 2971991
Fix fetch option forwarding 2df9b7e

v2.0.0...v2.0.1

Open source →

2.0.06 Apr 2026

Unify hook signatures around a single state object ( #827 ) ecdd45e

Breaking

Require Node.js 22 f1da0fc
Unify hook signatures around a single state object (#827) ecdd45e
- All hooks now receive a single {request, options, retryCount, ...} state object instead of separate arguments.
Rename prefixUrl to prefix, and allow leading slashes in input (#606) 1f2ad7f
Make beforeError hook receive all errors, not just HTTPError (#829) 101c74b
Make .json() throw on empty bodies and 204 responses instead of returning an empty string (#854) 1b8e1ff
Merge searchParams with input URL instead of replacing (#840) 29e78fe
Strip Ky-specific properties from normalized options passed to hooks (#826) 433febd
Treat hook errors as fatal outside retry handling (#834) 90c6d00

New

Add totalTimeout option for an overall timeout across all retries (#848) c20d7c7
Add baseUrl option for standard URL resolution (#606) 1f2ad7f
- baseUrl uses standard URL resolution: /users means origin-root, users means relative to the base path.
- prefix does simple string joining first, so /users and users both append to the prefix the same way. Use it only when you want that behavior.
Add data property to HTTPError with pre-parsed response body (#823) 1341f5c
- The response body is automatically consumed and parsed, fixing resource leaks and making error details immediately available without awaiting (#642).
Add init hook (#841) 87c6740
Add NetworkError class and tighten retry logic (#842) eaf0b80
Add Standard Schema validation for .json() (#830) 94741a9
Add replaceOption helper for .extend() (#846) bb8412e
Add request and options to beforeError hook state (#835) 01e0b85
Add request/response context to parseJson option (#849) 3713ce8
Don't throw HTTPError for opaque responses from no-cors requests (#847) 1d15eb6
Gracefully ignore onUploadProgress when request streams are unsupported (#845) 1e38ff4

Fixes

Fix beforeRequest hooks being skipped when a Request is returned (#832) aec65db
Ignore non-Errors returned by beforeError hooks (#833) a541fc0

Migration guide

Hook signatures

All hooks now receive a single state object instead of separate arguments.

hooks: {
-	beforeRequest: [(request, options) => {
+	beforeRequest: [({request, options}) => {
		request.headers.set('X-Custom', 'value');
	}],
-	afterResponse: [(request, options, response) => {
+	afterResponse: [({request, options, response}) => {
		log(response.status);
	}],
-	beforeRetry: [({request, options, error, retryCount}) => {
+	beforeRetry: [({request, options, error, retryCount}) => {
		// Same as before - beforeRetry already used an object
	}],
-	beforeError: [(error) => {
+	beforeError: [({error}) => {
		return error;
	}],
}

`prefixUrl` renamed to `prefix`

-ky('users', {prefixUrl: 'https://example.com/api/'});
+ky('users', {prefix: 'https://example.com/api/'});

Leading slashes in input are now allowed with prefix. There's also a new baseUrl option for standard URL resolution, which you may prefer over prefix.

`beforeError` hook receives all errors

Previously only received HTTPError. Now receives all error types. Use type guards:

+import {isHTTPError} from 'ky';

hooks: {
	beforeError: [
-		(error) => {
-			const {response} = error;
+		({error}) => {
+			if (isHTTPError(error)) {
+				const {response} = error;
+			}

			return error;
		}
	]
}

`.json()` on empty responses

.json() now throws a parse error on empty bodies and 204 responses instead of returning an empty string. This aligns with native JSON.parse behavior and surfaces the real issue; your code expected JSON but the server sent none.

Check the status before calling .json() if you expect empty responses:

const response = await ky('https://example.com/api');

if (response.status !== 204) {
    const data = await response.json();
}

Ky-specific options stripped from hooks

Ky-specific properties (hooks, json, parseJson, stringifyJson, searchParams, timeout, throwHttpErrors, fetch) are no longer available on the options object passed to hooks. If you need access to these values, store them in a variable outside the hook or use the context option to pass data between hooks.

`searchParams` merging

searchParams now merges with existing query parameters in the input URL instead of replacing them.

// v1: searchParams replaces ?existing=1
// v2: searchParams merges with ?existing=1
ky('https://example.com?existing=1', {searchParams: {added: 2}});
// => https://example.com?existing=1&added=2

`HTTPError` response body

error.response.json() and other body methods no longer work since the body is now automatically consumed. Use error.data instead, which has the pre-parsed response body immediately available.

-const body = await error.response.json();
-console.log(body.message);
+console.log(error.data.message);

This fixes resource leaks when catching HTTPError without consuming the body (#633) and makes error details synchronously available (#642). We considered cloning the response to keep both paths working, but that doubles memory usage for error bodies and adds edge cases around locked/large streams for little benefit. error.response is still available for headers and status.

Upgrading from `2.0.0-0`

`.json()` on empty responses

The behavior changed again from the prerelease. .json() now throws instead of returning undefined for empty bodies and 204 responses. The return type is back to Promise<T> (no more | undefined).

Thanks to @sholladay for helping with this update.

v1.14.3...v2.0.0

Open source →

2.0.0-029 Mar 2026pre-release

Nothing published for this version

1.14.325 Jan 2026

Fix empty context object being added to merged json body d7f7e73

Fix empty context object being added to merged json body d7f7e73

v1.14.2...v1.14.3

Open source →

1.14.226 Dec 2025

Fix response body cleanup after hooks ( #809 ) 2bdbd59

Fix response body cleanup after hooks (#809) 2bdbd59
Avoid awaiting response cancel on forced retry (#806) e673eaa
Make isKyError type guard include ForceRetryError (#801) 5791b66
Fix handling of uppercase retry.methods and improve typing (#789) cec10a9

v1.14.1...v1.14.2

Open source →

1.14.17 Dec 2025

Fix: Handle backoffLimit being undefined ( #796 ) 4fd8c28

Fix: Handle backoffLimit being undefined (#796) 4fd8c28

v1.14.0...v1.14.1

Open source →

1.14.04 Nov 2025

Add ky.retry() to force retries from afterResponse hooks ( #779 ) 68a5228

Add ky.retry() to force retries from afterResponse hooks (#779) 68a5228
Allow throwHttpErrors option to be a function (#781) 84ff3b9

v1.13.0...v1.14.0

Open source →

1.13.022 Oct 2025

Add context option ( #772 ) 1e749ba

Improvements

Add context option (#772) 1e749ba
- Usage example
Add retry.shouldRetry option (#767) f0fdbd4
Add retry.retryOnTimeout option (#767) f0fdbd4
Add retry.jitter option (#760) 081c924
Allow beforeRetry hooks to return a Request or Response (#774) a51bb1e

Fixes

Fix Next.js edge runtime next option support (#775) caf78d2
Fix compatibility with a non-standard Retry-After header (#771) c488be0

v1.12.0...v1.13.0

Open source →

1.12.014 Oct 2025

Add retry count to afterResponse and beforeError hooks (#763) 37fc250

Improvements

Add retry count to afterResponse and beforeError hooks (#763) 37fc250
Add retry count to beforeRequest hook (#754) b7572d0
Add type guards for errors (#746) 7e1fd0b

Fixes

Fix dispatcher option being ignored (#757) 5a3fc90
Fix hooks field incorrectly included in NormalizedOptions (#726) (#756) 0f2f00a
Fix searchParams option merging with URLSearchParams instances (#755) c847eec
Fix signal merging when using both instance and request options (#751) 2b0a100
Fix FormData content-type boundary regeneration when retrying in hooks (#752) d02b636

https://github.com/sindresorhus/ky/compare/v1.11.0...v1.12.0

Open source →

1.11.027 Sept 2025

Improve progress events for onDownloadProgress and onUploadProgress (#736) 60958f9

Improve progress events for onDownloadProgress and onUploadProgress (#736) 60958f9
Fix hang on stream request cleanup in Node.js (#741) 9a89a35

https://github.com/sindresorhus/ky/compare/v1.10.0...v1.11.0

Open source →

1.10.05 Sept 2025

Support undefined values for searchParams object (#729) a87d9e9

Support undefined values for searchParams object (#729) a87d9e9
Fix race condition issue with .json() (#731) 8cd79d3

https://github.com/sindresorhus/ky/compare/v1.9.1...v1.10.0

Open source →

1.9.128 Aug 2025

Fix uploadProgress with form data (#725) 3a8f89c

Fix uploadProgress with form data (#725) 3a8f89c

https://github.com/sindresorhus/ky/compare/v1.9.0...v1.9.1

Open source →

1.9.021 Aug 2025

Add .bytes() shortcut (#720) d112283

Add .bytes() shortcut (#720) d112283
Don't produce URL with "?" alone (#706) 17ca389

https://github.com/sindresorhus/ky/compare/v1.8.2...v1.9.0

Open source →

1.8.217 Jul 2025

Gracefully handle AbortSignal.any() not being available (#711) 24eec6f

Gracefully handle AbortSignal.any() not being available (#711) 24eec6f

https://github.com/sindresorhus/ky/compare/v1.8.1...v1.8.2

Open source →

1.8.114 Apr 2025

Improve reliability of cloned request cleanup (#693) 1f903ed

Improve reliability of cloned request cleanup (#693) 1f903ed

https://github.com/sindresorhus/ky/compare/v1.8.0...v1.8.1

Open source →

1.8.031 Mar 2025

Add `onUploadProgress` option (#632) a53fd34

Add onUploadProgress option (#632) a53fd34
Fix memory leak caused by shared abort signals (#683) e48386e
Fix memory leak for cloning the body for retry (#651) b49cd03

https://github.com/sindresorhus/ky/compare/v1.7.5...v1.8.0

Open source →

1.7.512 Feb 2025

Fix options.method being undefined in normalized options (#671) 762ea4c

Fix options.method being undefined in normalized options (#671) 762ea4c

https://github.com/sindresorhus/ky/compare/v1.7.4...v1.7.5

Open source →

1.7.418 Dec 2024

Fix handling of a signal that is already aborted before the request begins (#663) 6d06338

Fix handling of a signal that is already aborted before the request begins (#663) 6d06338

https://github.com/sindresorhus/ky/compare/v1.7.3...v1.7.4

Open source →

1.7.310 Dec 2024

Fix memory leak from cloned responses (#661) 30e7afd

Fix memory leak from cloned responses (#661) 30e7afd

https://github.com/sindresorhus/ky/compare/v1.7.2...v1.7.3

Open source →

1.7.22 Sept 2024

Types: Mark ky.create() options as optional (#628) 8d2ca91

Types: Mark ky.create() options as optional (#628) 8d2ca91

https://github.com/sindresorhus/ky/compare/v1.7.1...v1.7.2

Open source →

1.7.121 Aug 2024

Fix types for browsers (#623) 32a720d

Fix types for browsers (#623) 32a720d

https://github.com/sindresorhus/ky/compare/v1.7.0...v1.7.1

Open source →

1.7.017 Aug 2024

Add JSON generics to ky() and HTTPError (#619) f76c7cd

Add JSON generics to ky() and HTTPError (#619) f76c7cd

https://github.com/sindresorhus/ky/compare/v1.6.0...v1.7.0

Open source →

1.6.013 Aug 2024

Add support for the RateLimit-Reset header (#618) 8531b05

Add support for the RateLimit-Reset header (#618) 8531b05
Allow explicitly unsetting hooks on .extend() (#599) 0017053
Fix signal handling for Request objects (#613) 2376cf2

https://github.com/sindresorhus/ky/compare/v1.5.0...v1.6.0

Open source →

1.5.025 Jul 2024

Add `retry.afterStatusCodes` option (#598) 8764419

Add retry.afterStatusCodes option (#598) 8764419
Add support for passing a function to ky.extend() (#611) 9587c9d
TypeScript: Add KyRequest and KyResponse types (#610) 8e171f5
Retry request even if retry delay is zero (#604) 4886b66

https://github.com/sindresorhus/ky/compare/v1.4.0...v1.5.0

Open source →

1.4.026 Jun 2024

Add request method and URL to error messages (#595) 36d0bd3

Add request method and URL to error messages (#595) 36d0bd3
Clamp Retry-After time to retry.maxRetryAfter (#603) f0f9111
Fetch with an uncloned request when possible (#601) c5be841
Improve robustness of request construction (#600) 974f1e9
Improve detection of streaming request support (#581) (#582) b1effd9

https://github.com/sindresorhus/ky/compare/v1.3.0...v1.4.0

Open source →

1.3.031 May 2024

Add `stringifyJson` option (#579) 2eea67e

Add stringifyJson option (#579) 2eea67e

https://github.com/sindresorhus/ky/compare/v1.2.4...v1.3.0

Open source →

1.2.422 Apr 2024

Fix request types for use with Node.js (#578) 10a4ec7

Fix request types for use with Node.js (#578) 10a4ec7

https://github.com/sindresorhus/ky/compare/v1.2.3...v1.2.4

Open source →

1.2.324 Mar 2024

TypeScript: Fix usage with exactOptionalPropertyTypes config and compatibility with TypeScript 5.4 (#565) 08f912d

TypeScript: Fix usage with exactOptionalPropertyTypes config and compatibility with TypeScript 5.4 (#565) 08f912d

https://github.com/sindresorhus/ky/compare/v1.2.2...v1.2.3

Open source →

1.2.229 Feb 2024

Fix missing type dependency c0a4dfa

Fix missing type dependency c0a4dfa

https://github.com/sindresorhus/ky/compare/v1.2.1...v1.2.2

Open source →

1.2.125 Feb 2024

Fix compatibility with Cloudflare Workers (#559) d8ee602

Fix compatibility with Cloudflare Workers (#559) d8ee602

https://github.com/sindresorhus/ky/compare/v1.2.0...v1.2.1

Open source →

1.2.07 Jan 2024

Make types compatible with both DOM and Node.js (#543) 3cf5064

Improvements

Make types compatible with both DOM and Node.js (#543) 3cf5064
Export the Input TypeScript type (#552) 4dd4077

FIxes

Fix the retryCount option retrying an incorrect amount (#547) 917ab12

https://github.com/sindresorhus/ky/compare/v1.1.3...v1.2.0

Open source →

1.1.31 Nov 2023

Export the KyInstance type 16eb51d

Export the KyInstance type 16eb51d

https://github.com/sindresorhus/ky/compare/v1.1.2...v1.1.3

Open source →

1.1.229 Oct 2023

Fix multipart boundary mismatch (#540) 0e9d7bb

Fix multipart boundary mismatch (#540) 0e9d7bb

https://github.com/sindresorhus/ky/compare/v1.1.1...v1.1.2

Open source →

1.1.124 Oct 2023

Fix support for environments that add custom fetch options (#536) e93bc6d

Fix support for environments that add custom fetch options (#536) e93bc6d

https://github.com/sindresorhus/ky/compare/v1.1.0...v1.1.1

Open source →

1.1.017 Oct 2023

Add retry.delay option to control the time between retries (#533) c6181ef

Add retry.delay option to control the time between retries (#533) c6181ef

https://github.com/sindresorhus/ky/compare/v1.0.1...v1.1.0

Open source →

1.0.15 Sept 2023

Change Options and NormalizedOptions TypeScript types back to be interface 4d63a21

Change Options and NormalizedOptions TypeScript types back to be interface 4d63a21

https://github.com/sindresorhus/ky/compare/v1.0.0...v1.0.1

Open source →

1.0.01 Sept 2023

Require Node.js 18 (when used in Node.js) a8a3a26

Breaking

Require Node.js 18 (when used in Node.js) a8a3a26

Improvements

Ky can now run natively in Node.js without any polyfills 🎉
- This is thanks to Node.js 18+ having built-in support for fetch.
- This means ky-universal is no longer needed.

https://github.com/sindresorhus/ky/compare/v0.33.3...v1.0.0

Open source →

0.33.316 Mar 2023

Fix compatibility with native Fetch being disabled on Node.js (#494) 00e45d0

Fix compatibility with native Fetch being disabled on Node.js (#494) 00e45d0

https://github.com/sindresorhus/ky/compare/v0.33.2...v0.33.3

Open source →

0.33.213 Jan 2023

Fix the name of the error when aborting a request (#482) ce8588d

Fix the name of the error when aborting a request (#482) ce8588d

https://github.com/sindresorhus/ky/compare/v0.33.1...v0.33.2

Open source →

0.33.129 Dec 2022

Fix compatibility with Unidici ae2fe07

Fix compatibility with Unidici ae2fe07

https://github.com/sindresorhus/ky/compare/v0.33.0...v0.33.1

Open source →

0.33.012 Dec 2022

Add `retry.backoffLimit` option (#454) ab19baf

Add retry.backoffLimit option (#454) ab19baf

https://github.com/sindresorhus/ky/compare/v0.32.2...v0.33.0

Open source →

0.32.21 Nov 2022

Fix the empty check for .json() (#466) bf9eca6

Fix the empty check for .json() (#466) bf9eca6

https://github.com/sindresorhus/ky/compare/v0.32.1...v0.32.2

Open source →

0.32.131 Oct 2022

Don't return empty string for .json() if Transfer-Encoding is chunked (#464) 195e0e2

Don't return empty string for .json() if Transfer-Encoding is chunked (#464) 195e0e2

https://github.com/sindresorhus/ky/compare/v0.32.0...v0.32.1

Open source →

0.32.031 Oct 2022

Parse empty response bodies without throwing when using .json() (#459) 1cc6bbb

Parse empty response bodies without throwing when using .json() (#459) 1cc6bbb
Fix abortions between retries (#433) dddf7ba

https://github.com/sindresorhus/ky/compare/v0.31.4...v0.32.0

Open source →

0.31.412 Oct 2022

Fix Firefox compatibility for the onDownloadProgress option bccbfdb

Fix Firefox compatibility for the onDownloadProgress option bccbfdb

https://github.com/sindresorhus/ky/compare/v0.31.3...v0.31.4

Open source →

0.31.33 Sept 2022

Fix Node.js compatibility 0b141f1

Fix Node.js compatibility 0b141f1

https://github.com/sindresorhus/ky/compare/v0.31.2...v0.31.3

Open source →

0.31.22 Sept 2022

Fix Chrome 105 compatibility (#451) 316fffe

Fix Chrome 105 compatibility (#451) 316fffe

https://github.com/sindresorhus/ky/compare/v0.31.1...v0.31.2

Open source →

0.31.121 Jul 2022

Fix copying response body with 204 status code when using onDownloadProgress (#444) d48ed95

Fix copying response body with 204 status code when using onDownloadProgress (#444) d48ed95

https://github.com/sindresorhus/ky/compare/v0.31.0...v0.31.1

Open source →

0.31.023 Jun 2022

Require Node.js 14 when used in Node.js e557973

Breaking

Require Node.js 14 when used in Node.js e557973

Improvements

Add typed JSON response (#437) cff4c7a
Export BeforeRetryState type (#442) e4077b9

Fixes

Fix response details getting lost when using onDownloadProgress (#441) f34fb1f

https://github.com/sindresorhus/ky/compare/v0.30.0...v0.31.0

Open source →

0.30.02 Mar 2022

Allow overriding Content-Type header for JSON requests (#429) d00864f

Allow overriding Content-Type header for JSON requests (#429) d00864f

https://github.com/sindresorhus/ky/compare/v0.29.0...v0.30.0

Open source →

0.29.015 Feb 2022

Add `beforeError` hook (#417) 616d276

Add beforeError hook (#417) 616d276

https://github.com/sindresorhus/ky/compare/v0.28.7...v0.29.0

Open source →

0.28.78 Nov 2021

Fix source map generation (#396) b0e3001

Fix source map generation (#396) b0e3001

https://github.com/sindresorhus/ky/compare/v0.28.6...v0.28.7

Open source →

0.28.613 Oct 2021

Fix types for TypeScript 4.4 (#384) ca20d65

Fix types for TypeScript 4.4 (#384) ca20d65

https://github.com/sindresorhus/ky/compare/v0.28.5...v0.28.6

Open source →

0.28.531 May 2021

Export more TypeScript types ad991fa

Export more TypeScript types ad991fa

https://github.com/sindresorhus/ky/compare/v0.28.4...v0.28.5

Open source →

0.28.431 May 2021

Fix missing hook method types for TypeScript (#353) 8fc2f22

Fix missing hook method types for TypeScript (#353) 8fc2f22

https://github.com/sindresorhus/ky/compare/v0.28.3...v0.28.4

Open source →

0.28.328 May 2021

Fix incompatibility with New Relic (#351) 5f3c315

Fix incompatibility with New Relic (#351) 5f3c315

https://github.com/sindresorhus/ky/compare/v0.28.2...v0.28.3

Open source →

0.28.225 May 2021

Fix missing Options TypeScript type 3ad1eab

Fix missing Options TypeScript type 3ad1eab
Restore main field in package.json (#342) 1338996

https://github.com/sindresorhus/ky/compare/v0.28.1...v0.28.2

Open source →

0.28.114 May 2021

Fix searchParams option TypeScript type (#344) 010b082

Fix searchParams option TypeScript type (#344) 010b082

https://github.com/sindresorhus/ky/compare/v0.28.0...v0.28.1

Open source →

Your coding agent can read these notes before it upgrades. Set up the MCP server →

ky

Release timeline

Releases

Improvements

Fixes

Breaking

New

Fixes

Migration guide

Hook signatures

prefixUrl renamed to prefix

beforeError hook receives all errors

.json() on empty responses

Ky-specific options stripped from hooks

searchParams merging

HTTPError response body

Upgrading from 2.0.0-0

.json() on empty responses

Improvements

Fixes

Improvements

Fixes

Improvements

FIxes

Breaking

Improvements

Breaking

Improvements

Fixes

`prefixUrl` renamed to `prefix`

`beforeError` hook receives all errors

`.json()` on empty responses

`searchParams` merging

`HTTPError` response body

Upgrading from `2.0.0-0`

`.json()` on empty responses