Itchio-Downloader exports download functions, cookie cache utilities, and a resumable download helper. Import them from the package root.
The library requires Node.js 18+ for the native fetch API:
const {
downloadGame,
downloadGameDirect,
downloadGameHtml5,
downloadJam,
downloadWithResume,
getCachedCookies,
setCachedCookies,
clearCachedCookies,
} = require('itchio-downloader');Downloads one or more games from itch.io. Automatically selects the best download method using a priority chain (API key, HTML5, direct HTTP, auto-detect HTML5, Puppeteer fallback). When an array of parameter objects is supplied, multiple games can be fetched sequentially or in parallel.
params-- Either a singleDownloadGameParamsobject or an array of them. Each object accepts:name(string, optional) -- Game name, used withauthor.author(string, optional) -- Author's username on itch.io.itchGameUrl(string, optional) -- Direct URL to the game's page.desiredFileName(string, optional) -- Rename the downloaded file. Must not contain path separators.downloadDirectory(string, optional) -- Directory for the downloaded files. Defaults to~/downloads.apiKey(string, optional) -- itch.io API key for authenticated downloads. If omitted, the library checks theITCH_API_KEYenvironment variable.inMemory(boolean, optional) -- Store the downloaded file in memory and return it as a Buffer. When adownloadDirectoryis provided the file is also written to disk.writeMetaData(boolean, optional) -- Write a metadata JSON file alongside the download. Defaults totrue.html5(boolean, optional) -- Download HTML5 web game assets for offline play. When set, the library scrapes the game's embedded iframe and downloads all referenced assets (HTML, JS, CSS, images, audio, etc.) with directory structure preserved.platform(string, optional) -- Preferred platform for multi-upload games. Accepted values:'windows','linux','osx'.retries(number, optional) -- Number of retry attempts on failure. Defaults to0.retryDelayMs(number, optional) -- Base delay in milliseconds for exponential backoff. Defaults to500.navigationTimeoutMs(number, optional) -- Puppeteer page navigation timeout in milliseconds. Defaults to30000.fileWaitTimeoutMs(number, optional) -- Download file detection timeout in milliseconds. Defaults to30000.parallel(boolean, optional) -- When used inside an array, run this download concurrently viaPromise.all.resume(boolean, optional) -- Resume interrupted downloads using HTTP Range headers. Partial data is saved to a.partfile and the download continues from where it left off. Defaults tofalse.noCookieCache(boolean, optional) -- Disable automatic cookie caching. By default, session cookies and CSRF tokens are cached per domain with a 30-minute TTL to speed up subsequent downloads.cookieCacheDir(string, optional) -- Directory for the cookie cache file. Defaults to a subdirectory in the system temp directory.onProgress(function, optional) -- Receives{ bytesReceived, totalBytes, fileName }as the download proceeds.
concurrency(number, optional) -- Whenparamsis an array andparallelis not set, limits how many downloads happen at once. Defaults to1.
A promise that resolves to DownloadGameResponse or an array of responses.
Downloads a free itch.io game using direct HTTP requests -- no Puppeteer, no API key. This is the method used internally by downloadGame as the primary no-auth path.
Flow:
- GET the game page to extract CSRF token, upload IDs, cookies, and price info.
- POST to
/download_urlto get a signed download page URL. - GET the download page to get fresh CSRF and upload IDs.
- POST to
/file/{uploadId}to get a Cloudflare R2 CDN URL (60-second TTL). - Stream the CDN URL to disk or memory.
Session cookies and CSRF tokens are cached automatically (30-minute TTL) so subsequent downloads to the same domain skip step 1. When resume: true is set, interrupted downloads are saved as .part files and resumed using Range headers.
Accepts the same DownloadGameParams object. The most relevant fields are itchGameUrl (or name/author), downloadDirectory, desiredFileName, inMemory, writeMetaData, resume, noCookieCache, cookieCacheDir, and onProgress.
A Promise<DownloadGameResponse>.
Downloads an HTML5 web game from itch.io for offline play. Scrapes the embedded iframe URL (itch.zone/html/{id}/index.html), downloads index.html and all referenced assets, and saves them locally with directory structure preserved. JavaScript files are also scanned for additional asset references (images, audio, data files).
Accepts the same DownloadGameParams object. Set html5: true when calling via downloadGame, or call this function directly. The most relevant fields are itchGameUrl (or name/author), downloadDirectory, writeMetaData, and onProgress.
A Promise<DownloadGameResponse>. On success, the response includes:
html5Assets-- array of downloaded asset file paths relative to the game directory.filePath-- path to the savedindex.html.
Downloads all game entries from an itch.io game jam. Fetches the jam page to extract the jam ID, then retrieves all entries from the entries.json endpoint and downloads each game through the standard downloadGame pipeline.
jamUrl(string) -- URL to the jam page (e.g.,https://itch.io/jam/gmtk-2023).apiKey(string, optional) -- itch.io API key for authenticated downloads.opts(DownloadJamOptions, optional):downloadDirectory(string) -- Where to save downloaded files.concurrency(number) -- Maximum simultaneous downloads. Defaults to1.resume(boolean) -- Resume interrupted downloads.noCookieCache(boolean) -- Disable cookie caching.cookieCacheDir(string) -- Custom cookie cache directory.onProgress(function) -- Progress callback.
A Promise<DownloadGameResponse | DownloadGameResponse[]>. Returns a single error response if the jam has no entries, otherwise an array of results for each game.
const { downloadJam } = require('itchio-downloader');
const results = await downloadJam(
'https://itch.io/jam/gmtk-2023',
null,
{ concurrency: 3, downloadDirectory: './jam-games', resume: true },
);
// results is an array — one DownloadGameResponse per jam entry
for (const r of Array.isArray(results) ? results : [results]) {
console.log(r.status ? `Downloaded: ${r.filePath}` : `Failed: ${r.message}`);
}Download a file with automatic resume support. If a .part file exists from a previous interrupted download, sends a Range header to resume from where it left off. On success, renames .part to the final path.
url(string) -- URL to download.filePath(string) -- Final file path. Partial data is stored atfilePath + '.part'.headers(Record<string, string>, optional) -- Additional headers (e.g., User-Agent, Authorization).onProgress(function, optional) -- Progress callback.
A Promise<StreamResult>:
interface StreamResult {
bytesWritten: number;
expectedBytes?: number;
verified: boolean; // true if Content-Length matched actual bytes
resumed?: boolean; // true if download was resumed from partial
}Returns cached cookies for a URL's domain, or null if expired (30-min TTL) or missing.
Saves cookies and an optional CSRF token for a URL's domain.
Clears cached cookies for a specific domain, or all cached cookies if no URL is provided.
type DownloadGameParams = {
name?: string;
author?: string;
desiredFileName?: string;
downloadDirectory?: string;
apiKey?: string;
itchGameUrl?: string;
inMemory?: boolean;
writeMetaData?: boolean;
retries?: number;
retryDelayMs?: number;
navigationTimeoutMs?: number;
fileWaitTimeoutMs?: number;
parallel?: boolean;
html5?: boolean;
platform?: string;
resume?: boolean;
cookieCacheDir?: string;
noCookieCache?: boolean;
onProgress?: (info: DownloadProgress) => void;
};
type DownloadGameResponse = {
status: boolean;
message: string;
httpStatus?: number;
metaData?: IItchRecord;
metadataPath?: string;
filePath?: string;
fileBuffer?: Buffer;
html5Assets?: string[];
sizeVerified?: boolean;
bytesDownloaded?: number;
resumed?: boolean;
};
interface DownloadProgress {
bytesReceived: number;
totalBytes?: number;
fileName?: string;
}
interface IItchRecord {
title?: string;
coverImage?: string;
authors?: { url: string; name: string }[];
tags?: string[];
id?: number;
commentsLink?: string;
selfLink?: string;
author?: string;
name?: string;
domain?: string;
itchGameUrl?: string;
itchMetaDataUrl?: string;
}The metaData object mirrors the information fetched from the game's data.json file.
// Standard download (auto-selects best method)
await downloadGame({
itchGameUrl: 'https://baraklava.itch.io/manic-miners',
desiredFileName: 'manic-miners-latest',
});
// Direct HTTP download (no Puppeteer, no API key)
const result = await downloadGameDirect({
itchGameUrl: 'https://vfqd.itch.io/terra-nil',
downloadDirectory: './games',
});
// HTML5 web game download
const html5Result = await downloadGameHtml5({
itchGameUrl: 'https://ncase.itch.io/wbwwb',
downloadDirectory: './games',
});
console.log(html5Result.html5Assets);
// Platform-specific download
await downloadGame({
itchGameUrl: 'https://dev.itch.io/game',
apiKey: 'your-key',
platform: 'linux',
});
// Resumable download with size verification
const resumeResult = await downloadGame({
itchGameUrl: 'https://dev.itch.io/large-game',
resume: true,
});
console.log(resumeResult.resumed); // true if continued from .part
console.log(resumeResult.sizeVerified); // true if size matched
console.log(resumeResult.bytesDownloaded);
// Download all entries from a game jam
const jamResults = await downloadJam('https://itch.io/jam/gmtk-2023', null, {
concurrency: 3,
downloadDirectory: './jam-games',
});
// Cookie cache management
const { getCachedCookies, clearCachedCookies } = require('itchio-downloader');
const cached = await getCachedCookies('https://dev.itch.io/game');
await clearCachedCookies(); // clear allSee Advanced Usage for concurrency, HTML5, jams, and custom path examples. For troubleshooting and debug logs, see the Debugging guide.