igdb-wrapper

A type-safe TypeScript client for the IGDB API with a fluent query builder, automatic OAuth token handling, retries, and IGDB-friendly rate limiting.

The package is built for the way IGDB is normally used: start with a typed query, shape the fields you want, drop to raw APICalypse only when you need to, and keep your app code readable.

import { IGDBClient, buildImageUrl } from "@api-wrappers/igdb-wrapper";

const client = new IGDBClient({
  clientId: process.env.TWITCH_CLIENT_ID!,
  clientSecret: process.env.TWITCH_CLIENT_SECRET!,
});

const games = await client.games
  .query()
  .select((game) => ({
    id: game.id,
    name: game.name,
    rating: game.rating,
    cover: {
      imageId: game.cover.image_id,
    },
  }))
  .where((game, { or }) =>
    or(game.rating.gte(90), game.aggregated_rating.gte(90)),
  )
  .sort((game) => game.rating, "desc")
  .limit(5)
  .execute();

for (const game of games) {
  const coverUrl = game.cover?.imageId
    ? buildImageUrl(game.cover.imageId, { size: "cover_big", retina: true })
    : null;

  console.log(game.name, game.rating, coverUrl);
}

---

Why use it?

• Typed field selection with editor autocomplete for model fields and nested relations.
• Readable filters through .where(), or(), and(), and typed comparison helpers.
• Raw APICalypse escape hatches with .fields(), .whereRaw(), .apicalypse(), and endpoint.request().
• Every registered IGDB v4 endpoint exposed as a camel-cased IGDBClient property.
• Pagination helpers with .count() and async-generator .paginate().
• Automatic auth, retry, and rate limiting through @api-wrappers/api-core.
• Useful extras for image URLs, tag numbers, /meta, protobuf, multi-query, and webhooks.
• Structured errors so app code can handle auth, validation, rate limit, and not-found cases directly.

---

Installation

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

Requirements: Node.js 18+ (uses native fetch). TypeScript 5+ recommended.

---

Quick Start

IGDB uses Twitch application credentials. Create an app in the Twitch Developer Console, then set:

TWITCH_CLIENT_ID=your_client_id
TWITCH_CLIENT_SECRET=your_client_secret

import { IGDBClient } from "@api-wrappers/igdb-wrapper";

const client = new IGDBClient({
  clientId: process.env.TWITCH_CLIENT_ID!,
  clientSecret: process.env.TWITCH_CLIENT_SECRET!,
});

const game = await client.games
  .query()
  .select((game) => ({
    name: game.name,
    summary: game.summary,
    releaseDate: game.first_release_date,
  }))
  .where((game) => game.slug.eq("elden-ring"))
  .first();

console.log(game?.name);

---

Common Recipes

Search games

const results = await client.games
  .search("zelda")
  .select((game) => ({
    name: game.name,
    slug: game.slug,
    rating: game.rating,
  }))
  .where((game) => game.rating.gte(70))
  .limit(10)
  .execute();

Build a paginated list

const pageSize = 20;
const page = 2;

const query = client.games
  .query()
  .select((game) => ({ name: game.name, rating: game.rating }))
  .where((game) => game.rating_count.gte(100))
  .sort((game) => game.rating, "desc");

const [items, total] = await Promise.all([
  query.limit(pageSize).offset(page * pageSize).execute(),
  query.count(),
]);

Use raw IGDB syntax when needed

const games = await client.games
  .query()
  .fields("name", "platforms.name", "cover.image_id")
  .whereRaw("platforms = {48,6}")
  .apicalypse("limit 10;")
  .execute();

Fetch a cover URL

import { buildImageUrl } from "@api-wrappers/igdb-wrapper";

const game = await client.games
  .query()
  .select((game) => ({
    name: game.name,
    cover: { imageId: game.cover.image_id },
  }))
  .where((game) => game.slug.eq("hades"))
  .first();

const coverUrl = game?.cover?.imageId
  ? buildImageUrl(game.cover.imageId, { size: "cover_big", retina: true })
  : null;

---

Documentation

Guide	Description
Getting Started	Installation, credentials, and your first query
Querying	Full query builder API: select, where, sort, paginate
Examples	Copyable recipes for search, pagination, images, raw requests, and webhooks
Endpoints	All IGDB v4 endpoint properties and raw endpoint access
Error Handling	All error types and how to handle them
Configuration	Retry, rate limiting, and advanced options
API Reference	Complete method signatures

Example source files are also available in examples/.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

❤️

❤️ Reminder that you are great, you are enough, and your presence is valued. If you are struggling with your mental health, please reach out to someone you love and consult a professional. You are not alone. ❤️