CF-API-Wrapper (@larsj02/cf)

Simple, typed TypeScript wrapper around the CurseForge API.

Works with Node 18+ (built-in fetch). Provides enums and request/response types for a smooth dev experience.

Installation

npm install @larsj02/cf

You’ll need a CurseForge API key. Set it via environment variable:

export CF_API_KEY=your-key

Or copy the example env file and fill it in:

cp .env.example .env

Quick start

import { CurseForgeClient, ModsSearchSortField, ModLoaderType } from '@larsj02/cf';

const cf = new CurseForgeClient({ apiKey: process.env.CF_API_KEY! });

const res = await cf.mods.search({
	gameId: 1, // World of Warcraft
	searchFilter: 'bag',
	sortField: ModsSearchSortField.Popularity,
		sortOrder: 'desc',
	modLoaderType: ModLoaderType.Any,
});

console.log(res.data.map(m => m.name));

Examples

Build once, then run any example (they auto-load dotenv):

npm run build

# Mods
npm run example:search
npm run example:mods:featured

# Files
npm run example:files:download

# Categories / Versions
npm run example:categories
npm run example:versions

# Minecraft
npm run example:minecraft

# Fingerprints
npm run example:fingerprints

API surface

• Mods
  • search(params)
  • get(modId)
  • files(modId, pageSize?, index?)
  • description(modId)
  • getMany(ids)
  • featured(request)
• Files
  • get(modId, fileId)
  • getMany(fileIds)
  • changelog(modId, fileId)
  • downloadUrl(modId, fileId)
• Games
  • list()
  • get(id)
• Categories
  • list(gameId, classId?)
• Versions
  • getGameVersions(gameId)
  • getGameVersionTypes(gameId)
• Fingerprints
  • match({ fingerprints })
• Minecraft
  • versionLatest()
  • version(versionString)
  • modloaders()
  • modloader(name)

Enums included

• FileRelationType
• FileReleaseType
• FileStatus
• HashAlgo
• ModLoaderType
• ModsSearchSortField
• SortOrder ('asc' | 'desc')
• GameVersionTypeStatus
• ModStatus

Use them to strongly type your requests and check responses:

import { ModsSearchSortField, ModLoaderType, FileReleaseType } from '@larsj02/cf';

await cf.mods.search({
	gameId: 432, // Minecraft
	sortField: ModsSearchSortField.TotalDownloads,
	modLoaderTypes: [ModLoaderType.Forge, ModLoaderType.Fabric],
});

const file = (await cf.files.get(modId, fileId)).data;
if (file.releaseType === FileReleaseType.Release) {
	// stable
}

Node and fetch

• Node 18+ is required (global fetch).
• If you need a custom fetch (e.g., for proxies), pass it in the client options.

import { fetch as undiciFetch } from 'undici';
const cf = new CurseForgeClient({ apiKey: process.env.CF_API_KEY!, fetch: undiciFetch });

Dev scripts

npm run typecheck
npm run test
npm run build

Publish (maintainers)

This package is configured to publish ESM with types. To publish:

npm login
npm publish --access public

The prepublishOnly hook will build and run tests.

License

MIT