curseforge-api 🚀

This is a JavaScript module built around the new CurseForge for Studios API (also formerly known as "Eternal API" and "CurseForge Core API") following the deprecation of the older, unnofficial API. It is designed to be easy to use and has zero dependencies 🙌. More information about the CurseForge for Studios API is available here.

This module provides TypeScript typings.

This module uses fetch() under the hood to make requests. However, if you're using Node.js, keep in mind that fetch() was not added until v17.5.0, and is behind the --experimental-fetch flag until v18.0.0. For this reason, where fetch() is unavailable, the module can use a fetch polyfill such as node-fetch.

Table of Contents

1. Documentation
2. Installation
   1. Node.js
   2. Deno and Browser
3. Usage
   1. Using a fetch() Polyfill
   2. Documentation
   3. Examples
      1. Search for a mod via slug
      2. Fetch a mod via project ID
      3. Fetch the latest Forge 1.18.2 file for Just Enough Items (JEI)
      4. Fetch a mod file and download URL
4. Enums

Documentation

Documentation is available here and is automatically generated from the source with TypeDoc.

Installation

Import the package depending on what type of environment you're using it in.

Node.js

Install the package via npm:

npm install curseforge-api

and import it in your script:

import {CurseForgeClient} from 'curseforge-api';

Deno and Browser

Import modules directly via CDN (for example, esm.sh, Skypack, jsDelivr or unpkg):

// Recommended for Deno
import {CurseForgeClient} from 'https://esm.sh/curseforge-api';
// OR
import {CurseForgeClient} from 'https://cdn.skypack.dev/curseforge-api';
// OR
import {CurseForgeClient} from 'https://cdn.jsdelivr.net/npm/curseforge-api';
// OR
import {CurseForgeClient} from 'https://unpkg.com/curseforge-api'

Usage

Start by creating a client, which you will use to make most API queries:

const client = new CurseForgeClient('YOUR_API_KEY');

Using a fetch() Polyfill

If you're using Node.js < v17.5.0, you'll want to provide a fetch() polyfill such as node-fetch:

import fetch from 'node-fetch';

// Pass fetch to the client
const client = new CurseForgeClient('YOUR_API_KEY', {fetch});

You can also provide a different polyfill, for example, if you're running this in a browser environment and target older browsers that don't support fetch(). As seen above, simply pass the polyfilled fetch function to the client constructor via the options.

Documentation

All classes, functions, enums, and types are documented here.

Examples

Search for a mod via slug

import {CurseForgeGameEnum} from 'curseforge-api';

const modsResults = await client.searchMods(CurseForgeGameEnum.Minecraft, {slug: 'jei'});
const jei = modsResults.data[0];
console.log(jei.name); // => 'Just Enough Items (JEI)'
console.log(jei.id); // => 238222

Fetch a mod via project ID

const jei = await client.getMod(238222);
console.log(jei.name); // => 'Just Enough Items (JEI)'
console.log(jei.id); // => 238222

Fetch the latest Forge 1.18.2 file for Just Enough Items (JEI)

import {CurseForgeModLoaderType} from 'curseforge-api';

const files = await mod.getFiles(238222, {
    gameVersion: '1.18.2',
    modLoaderType: CurseForgeModLoaderType.Forge,
    pageSize: 1,
});
console.log(files.data[0].fileName); // => 'jei-1.18.2-9.7.1.232.jar'

Fetch a mod file and download URL

const file = await mod.getFile(3847103);
console.log(file.displayName); // => 'jei-1.18.2-9.7.0.209.jar'
console.log(await file.getDownloadURL()); // => 'https://edge.forgecdn.net/files/3847/103/jei-1.18.2-9.7.0.209.jar'

Enums

For convenience, the game IDs that were available at the time of publishing are available as an enum. You can use this wherever you need to provide a game ID.

There are also enums and typings available for all documented types on the CurseForge for Studios API.