https://github.com/minimusubi/curseforge-api
An easy to use library to help you consume the CurseForge for Studios API
https://github.com/minimusubi/curseforge-api
curseforge curseforge-api curseforge-core-api eternal-api
Last synced: about 1 year ago
JSON representation
An easy to use library to help you consume the CurseForge for Studios API
- Host: GitHub
- URL: https://github.com/minimusubi/curseforge-api
- Owner: minimusubi
- License: mit
- Created: 2022-07-25T12:50:43.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-15T16:48:17.000Z (about 2 years ago)
- Last Synced: 2025-04-03T00:24:11.192Z (about 1 year ago)
- Topics: curseforge, curseforge-api, curseforge-core-api, eternal-api
- Language: TypeScript
- Homepage: https://minimusubi.github.io/curseforge-api/
- Size: 452 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# curseforge-api 🚀
This is a JavaScript module built around the new [CurseForge for Studios API](https://docs.curseforge.com/#getting-started) (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](https://docs.curseforge.com/).
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](https://www.npmjs.com/package/node-fetch).
## Table of Contents
1. [Documentation](#documentation)
2. [Installation](#installation)
1. [Node.js](#nodejs)
2. [Deno and Browser](#deno-and-browser)
3. [Usage](#usage)
1. [Using a `fetch()` Polyfill](#using-a-fetch-polyfill)
2. [Documentation](#documentation-1)
3. [Examples](#examples)
1. [Search for a mod via slug](#search-for-a-mod-via-slug)
2. [Fetch a mod via project ID](#fetch-a-mod-via-project-id)
3. [Fetch the latest Forge 1.18.2 file for Just Enough Items (JEI)](#fetch-the-latest-forge-1182-file-for-just-enough-items-jei)
4. [Fetch a mod file and download URL](#fetch-a-mod-file-and-download-url)
4. [Enums](#enums)
## Documentation
Documentation is [available here](https://minimusubi.github.io/curseforge-api/) and is automatically generated from the source with [TypeDoc](https://typedoc.org/).
## Installation
Import the package depending on what type of environment you're using it in.
### Node.js
Install the package [via npm](https://www.npmjs.com/package/curseforge-api):
```
npm install curseforge-api
```
and import it in your script:
```js
import {CurseForgeClient} from 'curseforge-api';
```
### Deno and Browser
Import modules directly via CDN (for example, [esm.sh](https://esm.sh/), [Skypack](https://www.skypack.dev/), [jsDelivr](https://www.jsdelivr.com/) or [unpkg](https://www.unpkg.com/)):
```js
// 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](https://minimusubi.github.io/curseforge-api/classes/CurseForgeClient.html), which you will use to make most API queries:
```js
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](https://www.npmjs.com/package/node-fetch):
```js
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](https://minimusubi.github.io/curseforge-api/).
### Examples
#### Search for a mod via slug
```js
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
```js
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)
```js
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
```js
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](https://minimusubi.github.io/curseforge-api/enums/CurseForgeGameEnum.html). 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](https://docs.curseforge.com/#schemas).