ky

library0.0.5jsnpmunverified

Ky is a minimalist, elegant HTTP client for modern browsers, Node.js, Bun, and Deno, built as a wrapper around the native Fetch API. Its current stable version is 2.0.1, with major releases introducing significant breaking changes (e.g., v2.0.0). Ky distinguishes itself from plain `fetch` by providing a simpler API with convenient method shortcuts (e.g., `ky.post()`), automatic retries for failed requests, treating non-2xx status codes as errors by default, built-in JSON option handling, timeout support, upload/download progress, and a flexible hooks system for extending functionality. It also offers advanced features like base URL options, custom instances, and robust TypeScript generics for response types, significantly reducing boilerplate compared to raw Fetch. The library prides itself on being tiny and having no external dependencies, focusing on core HTTP client functionality.

http-networking web-framework

npm install ky

github ↗package ↗

INSTALL

IMPORT

SIG · KY

http-networkingjavascriptv0.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import ky from 'ky';

✗ const ky = require('ky');

Ky is primarily an ESM-first package. While CJS usage might be possible via transpilation or specific environments, direct `require` is generally incorrect for modern Node.js/browser setups.

HTTPError

✓ import { HTTPError } from 'ky';

The `HTTPError` class is a named export, useful for precisely catching HTTP-related errors.

Options

✓ import type { Options } from 'ky';

Type-only import for configuring Ky instances or individual requests, ensuring type safety in TypeScript projects.

This example demonstrates how to perform both POST and GET requests using Ky, including sending JSON payloads, handling search parameters, setting request timeouts, and configuring automatic retries. It also illustrates robust error handling by catching `HTTPError` instances to access detailed response information in case of non-2xx status codes, showcasing Ky's streamlined API compared to native Fetch.

import ky, { HTTPError } from 'ky'; async function fetchData() { try { // Example: POST request with JSON payload console.log('Sending POST request...'); const postResult = await ky.post('https://jsonplaceholder.typicode.com/posts', { json: { title: 'foo', body: 'bar', userId: 1 }, headers: { 'Content-type': 'application/json; charset=UTF-8' }, timeout: 5000 // Set a timeout for the request }).json(); console.log('POST request successful:', postResult); // Example: GET request with search parameters and custom options console.log('\nSending GET request...'); const getResult = await ky.get('https://jsonplaceholder.typicode.com/comments', { searchParams: { postId: 1 }, retry: { limit: 2, // Retry up to 2 times on failure methods: ['get'] } }).json(); console.log('GET request successful, first comment:', getResult[0]); } catch (error) { if (error instanceof HTTPError) { const { request, response, options } = error; console.error(`HTTP Error: ${response.status} - ${response.statusText}`); console.error(`Request URL: ${request.url}`); console.error(`Response body: ${await response.text()}`); } else { console.error('An unexpected error occurred:', error); } } } fetchData();

Debug

Known issues

breakingKy v2.0.0 and above requires Node.js 22 or newer. Projects running on older Node.js versions must upgrade Node.js or stick to Ky v1.x.

fix

Upgrade your Node.js runtime to version 22 or later. If unable to upgrade, use `npm install ky@^1`.

affects: >=2.0.0

breakingAll Ky hooks (e.g., `beforeRequest`, `afterResponse`, `beforeRetry`) now receive a single state object (`{request, options, retryCount, ...}`) instead of separate, individual arguments.

fix

Refactor hook functions to destructure the single state object. For example, `(request, options)` becomes `({ request, options })`.

affects: >=2.0.0

breakingThe `prefixUrl` option has been renamed to `prefix` to better reflect its purpose and consistency. It now also allows leading slashes in the input.

fix

Replace all instances of `prefixUrl` in your Ky options with `prefix`. For example, `ky.extend({ prefixUrl: '...' })` becomes `ky.extend({ prefix: '...' })`.

affects: >=2.0.0

breakingThe `beforeError` hook signature changed to receive a state object, similar to other hooks. This affects how the hook receives the error, request, and options.

fix

Update `beforeError` hook implementations to accept the unified state object. Refer to the Ky documentation for the exact structure of the state object passed to this hook.

affects: >=2.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

Attempting to use CommonJS `require()` syntax in a modern JavaScript project that is configured for ES Modules, or when Ky is installed as an ESM-only package.

fix

Use ES Module import syntax: `import ky from 'ky';` Ensure your project's `package.json` includes `"type": "module"` or uses `.mjs` file extensions for ESM.

TypeError: ky.get(...).json is not a function

Forgetting to `await` the initial Ky request call before attempting to call a response body method like `.json()`, `.text()`, etc.

fix

Ensure you `await` the Ky request: `const data = await ky.get(url).json();`

HTTPError: Fetch error: Not Found

Ky automatically throws an `HTTPError` for non-2xx status codes (like 404 Not Found), unlike the native Fetch API which only rejects for network errors.

fix

Wrap your Ky calls in a `try...catch` block to handle `HTTPError` instances. You can inspect `error.response.status` and `error.response.statusText` for details.

Upgrade

Version history

0.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/sindresorhus/ky ↗

packagehttps://www.npmjs.com/package/ky ↗