{"id":10399,"library":"ky","title":"Ky HTTP Client","description":"Ky is a tiny and elegant HTTP client based on the Fetch API, providing a simpler API with features like method shortcuts, automatic retries, JSON option, timeout support, upload/download progress, and instances with custom defaults. It treats non-2xx status codes as errors by default, unlike plain Fetch. The current stable version is 2.0.1, and the library is actively developed with regular updates.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/sindresorhus/ky","tags":["javascript","fetch","request","requests","http","https","fetching","get","url","typescript"],"install":[{"cmd":"npm install ky","lang":"bash","label":"npm"},{"cmd":"yarn add ky","lang":"bash","label":"yarn"},{"cmd":"pnpm add ky","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Ky is an ESM-only package and requires Node.js 22+ since v2.","symbol":"ky","correct":"import ky from 'ky';"}],"quickstart":{"code":"import ky from 'ky';\n\nconst exampleJson = await ky.post('https://example.com', {\n  json: { foo: true },\n}).json();\n\nconsole.log(exampleJson);\n// => {data: '🦄'}","lang":"typescript","description":"Demonstrates making a POST request with JSON payload to an example URL and logging the parsed JSON response."},"warnings":[{"fix":"Upgrade your Node.js environment to version 22 or higher. For older Node.js versions, use Ky v1.x.","message":"Ky v2.0.0 and later require Node.js 22 or newer.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your hook functions to destructure the state object. For example, change `(request, options) => { ... }` to `({request, options}) => { ... }`.","message":"All Ky hooks (e.g., `beforeRequest`, `afterResponse`, `beforeError`) now receive a single state object (`{request, options, retryCount, ...}`) instead of separate arguments.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace `prefixUrl: '...'` with `prefix: '...'` in your Ky options.","message":"The `prefixUrl` option has been renamed to `prefix`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Wrap your Ky calls in a `try...catch` block to handle `HTTPError` for non-successful responses. To disable this behavior, set `throwHttpErrors: false` in your options.","message":"Unlike plain `fetch`, Ky automatically throws an `HTTPError` for non-2xx status codes (e.g., 404 Not Found, 500 Internal Server Error) after redirects. This behavior is enabled by default.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure your API returns a valid JSON body for endpoints where you use `.json()`. For 204 responses or empty bodies, use `.text()` or handle the error in a `try...catch` block.","message":"The `.json()` shortcut method throws an error if the response body is empty or the HTTP status is 204 No Content, as it expects valid JSON content.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and you are using Node.js 22 or higher. Alternatively, ensure your bundler properly transpiles ESM.","cause":"Attempting to use ES Module `import` syntax in a CommonJS environment or an older Node.js version that does not support ESM without explicit configuration.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Verify your import statement: `import ky from 'ky';`. Confirm your environment supports ESM and Ky's Node.js version requirement.","cause":"Ky was not imported correctly, or the `ky` variable is `undefined`/`null`, often due to an incorrect import path or using `require()` for an ESM-only package.","error":"TypeError: ky.post is not a function"},{"fix":"Check the URL, `prefix` option, and any `searchParams` for correctness. Handle `HTTPError` in your `try...catch` block to manage API errors gracefully.","cause":"The requested resource was not found on the server. Ky automatically throws an `HTTPError` for any non-2xx status code.","error":"HTTPError: Not Found (404)"},{"fix":"Update your hook signature. For example, change `(request, options) => { console.log(options.headers); }` to `({request, options}) => { console.log(options.headers); }`.","cause":"A Ky hook function, like `beforeRequest`, is attempting to access properties of its second argument (e.g., `options`), but the hook signature changed in v2 to expect a single state object, making subsequent arguments `undefined`.","error":"TypeError: Cannot read properties of undefined (reading 'headers') in Ky hook"},{"fix":"Rename `prefixUrl` to `prefix` in your Ky options. Ensure that `input` is a valid relative path if relying on the `prefix` option for the base URL.","cause":"After upgrading to Ky v2, the `prefixUrl` option was used, but it has been renamed to `prefix`. Ky did not apply the base URL, leading to an invalid or relative URL being passed to `fetch`.","error":"Failed to construct 'URL': Invalid URL"}],"ecosystem":"npm"}