README.md

curseforge-js

A framework-agnostic fully typed JavaScript client for the CurseForge API.

📚 Docs • 🚀 Getting Started • 📖 API Reference • 📝 Changelog

📦 Installation

npm install curseforge-js
pnpm add curseforge-js
yarn add curseforge-js
bun add curseforge-js

🚀 Usage

import CurseForgeClient from 'curseforge-js';

const client = new CurseForgeClient({
  apiKey: 'your-api-key',
  userAgent: 'my-app/1.0',
});

const mod = await client.mods.get(238222);
const files = await client.files.list(238222);

console.log(mod);
console.log(files);

📖 API

new CurseForgeClient(options)

const client = new CurseForgeClient({
  baseUrl: 'https://api.curseforge.com',
  apiKey: 'your-api-key',
  timeoutMs: 10_000,
  userAgent: 'my-app/1.0',
});

Options

interface CurseForgeClientOptions {
  baseUrl?: string;   // default: "https://api.curseforge.com"
  apiKey?: string;
  timeoutMs?: number; // default: 10000
  userAgent?: string;
  fetch?: typeof globalThis.fetch;
}

Selected Methods

Games:

• client.games.list(options?)
• client.games.get(gameId)
• client.games.getVersions(gameId)
• client.games.getVersionsV2(gameId)
• client.games.getVersionTypes(gameId)

Categories:

• client.categories.list(options)

Minecraft:

• client.minecraft.getVersions(options?)
• client.minecraft.getVersion(gameVersionString)
• client.minecraft.getModLoaders(options?)
• client.minecraft.getModLoader(modLoaderName)

Mods:

• client.mods.search(options)
• client.mods.get(modId)
• client.mods.getMods(body)
• client.mods.getFeatured(body)
• client.mods.getDescription(modId, options?)

Files:

• client.files.get(modId, fileId)
• client.files.list(modId, options?)
• client.files.getFiles(body)
• client.files.getChangelog(modId, fileId)
• client.files.getDownloadUrl(modId, fileId)

Fingerprints:

• client.fingerprints.getMatches(fingerprints, gameId?)
• client.fingerprints.getFuzzyMatches(fingerprints, gameId?)

Users:

• client.users.get(userId)

🔐 Authentication

Get an API key from console.curseforge.com, then pass it at client creation time. It is sent as the x-api-key header on every request.

const client = new CurseForgeClient({
  apiKey: 'your-api-key',
});

const mod = await client.mods.get(238222);

🌐 Custom Fetch

You can inject your own fetch implementation.

import CurseForgeClient from 'curseforge-js';
import fetch from 'node-fetch';

const client = new CurseForgeClient({
  apiKey: 'your-api-key',
  fetch,
});

⚠️ Error Handling

All request, timeout, and API errors are thrown as CurseForgeError.

import CurseForgeClient, { CurseForgeError } from 'curseforge-js';

const client = new CurseForgeClient({ apiKey: 'your-api-key' });

try {
  await client.mods.get(0);
} catch (error) {
  if (error instanceof CurseForgeError) {
    console.error(error.status);
    console.error(error.message);
    console.error(error.body);
  }
}

👨‍💻 Development

pnpm build

pnpm test

🤝 Contributing

Contributions are always welcome!

Please ensure you run pnpm lint:fix before opening a pull request.

📜 License

MIT