The ky npm package is a tiny and elegant HTTP client based on the browser's Fetch API. It provides a simpler and more powerful interface for making HTTP requests and handling responses. It is designed to be used with modern JavaScript, including support for async/await syntax.
GET requests
This feature allows you to perform GET requests to retrieve data from a specified resource. The example code demonstrates how to make a GET request and parse the response as JSON.
const json = await ky.get('https://jsonplaceholder.typicode.com/todos/1').json();POST requests
This feature enables you to send POST requests to submit data to a server. The example code shows how to make a POST request with a JSON body and parse the response as JSON.
const json = await ky.post('https://jsonplaceholder.typicode.com/posts', { json: { title: 'foo', body: 'bar', userId: 1 } }).json();Error handling
Ky provides simple error handling for failed HTTP requests. The example code demonstrates how to catch errors when a request fails, such as when the URL is invalid.
ky.get('https://jsonplaceholder.typicode.com/invalid-url').then(response => console.log(response)).catch(error => console.error(error));Timeouts
Ky allows you to specify a timeout for the request. If the request takes longer than the specified time, it will be aborted. The example code sets a timeout of 5000 milliseconds.
ky.get('https://jsonplaceholder.typicode.com/todos', { timeout: 5000 }).then(response => console.log(response));Hooks
Ky provides hooks that allow you to intercept requests and responses to perform actions or modify them. The example code logs a message before the request is made.
ky.get('https://jsonplaceholder.typicode.com/todos', { hooks: { beforeRequest: [request => { console.log('About to make a request', request); }] } }).then(response => console.log(response));Axios is a popular HTTP client for the browser and node.js. It supports promise-based API, interceptors, request cancellation, and more. Compared to ky, axios works in both the browser and Node.js environments, while ky is designed primarily for modern browsers.
Got is a powerful HTTP client for Node.js. It provides a lot of features like streams, retries, and advanced error handling. Unlike ky, which is built on the Fetch API, got is more suitable for server-side use and offers a wider range of options for Node.js developers.
node-fetch is a light-weight module that brings the browser's Fetch API to Node.js. It aims to provide a consistent API with the browser's Fetch, making it a closer alternative to ky for server-side development. However, ky offers additional features and a more fluent API on top of the basic Fetch functionality.
Superagent is a small progressive client-side HTTP request library. It has a flexible and expressive API that allows for chaining methods. Superagent is similar to ky in terms of client-side usage but does not rely on the Fetch API and has a different API design.
Ky is a tiny and elegant HTTP client based on the browser Fetch API
Ky targets modern browsers. For older browsers, you will need to transpile and use a fetch polyfill. For Node.js, check out Got.
1 KB (minified & gzipped), one file, and no dependencies.
fetchky.post())$ npm install ky
import ky from 'ky';
(async () => {
const json = await ky.post('https://example.com', {json: {foo: true}}).json();
console.log(json);
//=> `{data: '🦄'}`
})();
With plain fetch, it would be:
(async () => {
class HTTPError extends Error {}
const response = await fetch('https://example.com', {
method: 'POST',
body: JSON.stringify({foo: true}),
headers: {
'content-type': 'application/json'
}
});
if (!response.ok) {
throw new HTTPError('Fetch error:', response.statusText);
}
const json = await response.json();
console.log(json);
//=> `{data: '🦄'}`
})();
The input and options are the same as fetch, with some exceptions:
credentials option is same-origin by default, which is the default in the spec too, but not all browsers have caught up yet.Returns a Response object with Body methods added for convenience. So you can, for example, call ky.json() directly on the Response without having to await it first. Unlike the Body methods of window.Fetch; these will throw an HTTPError if the response status is not in the range 200...299.
Sets options.method to the method name and makes a request.
Type: Object
Type: Object
Shortcut for sending JSON. Use this instead of the body option. Accepts a plain object which will be JSON.stringify()'d and the correct header will be set for you.
Type: string Object<string, string|number> URLSearchParams
Default: ''
Search parameters to include in the request URL. Setting this will override all existing search parameters in the input URL.
Type: string URL
When specified, prefixUrl will be prepended to input. The prefix can be any valid URL, either relative or absolute. A trailing slash / is optional, one will be added automatically, if needed, when joining prefixUrl and input. The input argument cannot start with a / when using this option.
Useful when used with ky.extend() to create niche-specific Ky-instances.
import ky from 'ky';
// On https://example.com
(async () => {
await ky('unicorn', {prefixUrl: '/api'});
//=> 'https://example.com/api/unicorn'
await ky('unicorn', {prefixUrl: 'https://cats.com'});
//=> 'https://cats.com/unicorn'
})();
Type: number
Default: 2
Retry failed requests made with one of the below methods that result in a network error or one of the below status codes.
Methods: GET PUT HEAD DELETE OPTIONS TRACE
Status codes: 408 413 429 500 502 503 504
It adheres to the Retry-After response header.
Type: number
Default: 10000
Timeout in milliseconds for getting a response.
Type: Object<string, Function[]>
Default: {beforeRequest: []}
Hooks allow modifications during the request lifecycle. Hook functions may be async and are run serially.
Type: Function[]
Default: []
This hook enables you to modify the request right before it is sent. Ky will make no further changes to the request after this. The hook function receives the normalized options as the first argument. You could, for example, modify options.headers here.
Type: Function[]
Default: []
This hook enables you to read and optionally modify the response. The hook function receives a clone of the response as the first argument. The return value of the hook function will be used by Ky as the response object if it's an instance of Response.
ky.get('https://example.com', {
hooks: {
afterResponse: [
response => {
// You could do something with the response, for example, logging.
log(response);
// Or return a `Response` instance to overwrite the response.
return new Response('A different response', {status: 200});
}
]
}
});
Type: boolean
Default: true
Throw a HTTPError for error responses (non-2xx status codes).
Setting this to false may be useful if you are checking for resource availability and are expecting error responses.
Create a new ky instance with some defaults overridden with your own.
import ky from 'ky';
// On https://my-site.com
const api = ky.extend({prefixUrl: 'https://example.com/api'});
(async () => {
await api.get('/users/123');
//=> 'https://example.com/api/users/123'
await api.get('/status', {prefixUrl: ''});
//=> 'https://my-site.com/status'
})();
Type: Object
Exposed for instanceof checks. The error has a response property with the Response object.
The error thrown when the request times out.
Fetch (and hence Ky) has built-in support for request cancelation through the AbortController API. Read more.
Example:
import ky from 'ky';
const controller = new AbortController();
const {signal} = controller;
setTimeout(() => controller.abort(), 5000);
(async () => {
try {
console.log(await ky(url, {signal}).text());
} catch (error) {
if (error.name === 'AbortError') {
console.log('Fetch aborted');
} else {
console.error('Fetch error:', error);
}
}
})();
gotSee my answer here. Got is maintained by the same people as Ky.
axios?See my answer here.
r2?See my answer in #10.
ky mean?It's just a random short npm package name I managed to get. It does, however, have a meaning in Japanese:
A form of text-able slang, KY is an abbreviation for 空気読めない (kuuki yomenai), which literally translates into “cannot read the air.” It's a phrase applied to someone who misses the implied meaning.
The latest version of Chrome, Firefox, and Safari.
MIT
FAQs
Tiny and elegant HTTP client based on the Fetch API
The npm package ky receives a total of 365,115 weekly downloads. As such, ky popularity was classified as popular.
We found that ky demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.