kitsu

library11.1.0jsnpmunverified

A simple, lightweight and framework-agnostic JSON:API client using Axios. Version 11.1.0 (stable) supports Node 18+ and modern browsers (Chrome 116+, Firefox 118+, Safari 17.1+). Key differentiators: automatically resolves relationships (flattening `included` into data), works in both Node and browsers, and provides a clean Promise-based API. Compared to other JSON:API clients like `jsonapi-client` or `jsonapi-datastore`, Kitsu focuses on simplicity and zero-config usage for the Kitsu.app API (anime/manga) but works with any JSON:API-compliant server. Ships TypeScript definitions. Released under MIT license.

productivity

npm install kitsu

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KITSU

kitsu

productivityjavascriptv11.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Kitsu

✓ import Kitsu from 'kitsu'

✗ const Kitsu = require('kitsu')

Default export is the class constructor. CommonJS require works in Node, but ESM is recommended. The library is ESM-first but provides CJS compatibility.

Kitsu

✓ import { Kitsu } from 'kitsu'

Named export also available since v11. Both default and named exports refer to the same class. Prefer default import for consistency.

kitsu types

✓ import type { KitsuOptions, KitsuResponse } from 'kitsu'

TypeScript types are shipped with the package; no separate @types/kitsu needed. Use `import type` for type-only imports.

Shows instantiation with default and custom baseURL, then CRUD operations (get, create, update, remove) with common JSON:API parameters like filtering, sorting, and pagination.

import Kitsu from 'kitsu'; // Create an instance configured for kitsu.app const api = new Kitsu(); // Or for a custom JSON:API server const api = new Kitsu({ baseURL: 'https://api.example.com/v2' }); async function main() { // Fetch resources const anime = await api.get('anime', { params: { filter: { status: 'current' }, sort: '-popularityRank', page: { limit: 5 } } }); console.log(anime.data); // Create a resource const created = await api.create('posts', { title: 'Hello', content: 'World' }); // Update a resource await api.update('posts', { id: '1', title: 'Updated' }); // Delete a resource await api.remove('posts', '1'); } main().catch(console.error);

Debug

Known issues

breakingIn v11, the package is ESM-only. Node 12/14/16 are no longer supported. You must upgrade to Node 18 or later and use ESM imports (`import` instead of `require`).

fix

Upgrade to Node 18+. Use `import Kitsu from 'kitsu'` instead of `require('kitsu')`. If you must use CommonJS, use dynamic import: `const { default: Kitsu } = await import('kitsu')`.

affects: >=11.0.0

breakingIn v10, the `api.get()` method no longer returns a plain object but a `KitsuResponse` wrapper. This may break code relying on the previous return shape.

fix

Access data via `response.data` (or use destructuring: `const { data } = await api.get(...)`) instead of using the response directly as the data object.

affects: >=10.0.0

deprecatedThe `.fetch()` method is deprecated in favor of `.get()` in v11. Using `.fetch()` may be removed in future releases.

fix

Replace `api.fetch('resource')` with `api.get('resource')`.

affects: >=11.0.0

gotchaWhen using `api.update()`, the id must be included in the payload object, not as a separate parameter. Omitting the id will cause a 400 error from the server.

fix

Always include `id` in the data object: `api.update('posts', { id: '1', title: 'Updated' })`. Do not pass id as a second argument.

affects: >=9.0.0

gotchaThe `baseURL` option must end without a trailing slash (e.g., `'https://api.example.com/v2'`). A trailing slash can cause double slashes in request URLs.

fix

Ensure your baseURL does not end with a `/`. For example, use `'https://api.example.com/v2'` instead of `'https://api.example.com/v2/'`.

affects: >=9.0.0

Errors

Common errors & fixes

TypeError: kitsu_1.default is not a constructor

Using `require('kitsu')` with an ESM-only package in Node 12-16.

fix

Upgrade to Node 18+. Use `import Kitsu from 'kitsu'` if possible. For CommonJS workaround: `const { default: Kitsu } = require('kitsu')`.

Cannot find module 'kitsu' or its corresponding type declarations

Missing `kitsu` installation or misconfigured TypeScript module resolution.

fix

Run `npm install kitsu` or `yarn add kitsu`. Ensure tsconfig.json has `"moduleResolution": "node"` (or `node16`/`bundler`) and `"esModuleInterop": true`.

Error: Request failed with status code 404

API endpoint does not exist or baseURL is incorrect.

fix

Verify the baseURL. For kitsu.app API, use default (no baseURL). For custom servers, ensure the URL is correct and includes the version if needed. Check that the resource type is pluralized correctly (e.g., 'anime' not 'animes').

TypeError: Cannot read properties of undefined (reading 'data')

Trying to access `response.data` but response is undefined, often due to mishandling async/await or promise chains.

fix

Ensure you are awaiting the request: `const response = await api.get('anime')`. If using .then(), chain correctly: `api.get('anime').then(response => console.log(response.data))`.

Upgrade

Version history

11.1.0latest on npm

Audit

Dependencies

axiosrequiredHTTP client used for all API requests

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wopian/kitsu ↗

packagekitsu ↗

homepagehttps://github.com/wopian/kitsu/tree/master/packages/kitsu#readme ↗