AniList Wrapper

A type-safe TypeScript client for the AniList GraphQL API. Use the convenience services for common anime, manga, character, staff, user, and list workflows, or drop down to raw GraphQL when AniList exposes something the wrapper does not cover yet.

If this package saves you time, star the repo to help other AniList developers find it.

Install

npm install @api-wrappers/anilist-wrapper
# or
bun add @api-wrappers/anilist-wrapper
# or
pnpm add @api-wrappers/anilist-wrapper
# or
yarn add @api-wrappers/anilist-wrapper

First Query

import { Anilist } from "@api-wrappers/anilist-wrapper";

const anilist = new Anilist();

const { Media } = await anilist.anime.getAnimeById(16498);

console.log(Media?.title?.userPreferred);
console.log(Media?.siteUrl);

Most read-only methods do not need a token. Create an authenticated client only when you need private user data or mutations:

const anilist = new Anilist(process.env.ANILIST_TOKEN);

Common Workflows

Search anime

const results = await anilist.anime.getAnimeBySearch("Frieren", 1, 5);

for (const media of results.Page?.media ?? []) {
	console.log(media?.title?.userPreferred, media?.startDate?.year);
}

Get trending manga

const trending = await anilist.manga.getMangaTrending(1, 10);

const titles = trending.Page?.media
	?.map((media) => media?.title?.userPreferred)
	.filter(Boolean);

console.log(titles);

Read a public user list

const list = await anilist.user.getUserAnimeListByUsername("example_user");

for (const group of list.MediaListCollection?.lists ?? []) {
	console.log(group?.name, group?.entries?.length ?? 0);
}

Update the authenticated user's list

import { MediaListStatus } from "@api-wrappers/anilist-wrapper";

const anilist = new Anilist(process.env.ANILIST_TOKEN);

const saved = await anilist.mediaList.saveEntry({
	mediaId: 16498,
	status: MediaListStatus.Current,
	progress: 1,
	score: 8,
});

console.log(saved.SaveMediaListEntry?.id);

Use raw GraphQL

import { Anilist, gql } from "@api-wrappers/anilist-wrapper";

const anilist = new Anilist();

const data = await anilist.graphql.request<{
	GenreCollection: Array<string | null> | null;
}>(gql`
	query Genres {
		GenreCollection
	}
`);

console.log(data.GenreCollection);

Services

| Property | Use it for | | --- | --- | | anilist.anime | Anime lookup, search, trending, popular, genre, relations, characters, staff, recommendations, favorites | | anilist.manga | Manga lookup, search, trending, popular, genre, relations, characters, staff, recommendations, favorites | | anilist.character | Character lookup, birthdays, favorites | | anilist.staff | Staff lookup, birthdays, favorites | | anilist.user | User profiles, public lists by username, authenticated list/stat queries by user ID | | anilist.media | Generic anime/manga media lookup and list access | | anilist.mediaList | Media list entry lookup, save, and delete | | anilist.graphql | Any AniList GraphQL query or mutation |

Docs And Examples

• Documentation home
• Authentication guide
• API reference
• Runnable examples

Run examples directly from this repo:

bun examples/basic-anime.ts
bun examples/manga-workflow.ts
bun examples/raw-graphql.ts
ANILIST_TOKEN=... ANILIST_USERNAME=... bun examples/authenticated-user.ts

Development

bun install
bun test
bun run check
bun run build

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md before contributing.

License

MIT