Zim Utils

Native, dependency-light ZIM archive reader/searcher and Kiwix catalog downloader for Node.js

---

Documentation • Release Notes • Report a Bug • Request a Feature

---

Table of Contents

• Zim Utils
  • About
    • Built With
  • Setup
    • Production
  • Usage
    • ZimManager
    • ZimReader
    • Catalog
  • License

About

@ztimson/zim-utils is a native, dependency-light toolkit for working with ZIM archives and the Kiwix catalog in Node.js

It comes with the following helpers:

• ZimManager — Local library manager: listing, updating/downloading, and running searches accross the entire library
• ZimReader — A .zim file reader for reading pages, metadata and running searches
• Catalog (zimCatalog/zimCatalogInfo) — Helper functions to search the Kiwix OPDS catalog

Built With

Setup

Production

Prerequisites

• Node.js

Instructions

1. Install the dependencies: npm install
2. Install the package: npm install @ztimson/zim-utils

Usage

ZimManager

ZimManager owns a directory of .zim files and handles everything from downloading to cross-archive search.

import {ZimManager} from '@ztimson/zim-utils';

const manager = new ZimManager('./zims'); // optional 2nd arg: custom catalog URL

// Search the Kiwix catalog & download the top hit
const [entry] = await manager.catalog('wikipedia,medicine');
await manager.download(entry.href);

// List local archives with their parsed metadata
const local = await manager.list();
// [{file: './zims/wikipedia_en_medicine.zim', meta: {name, date, title}}, ...]

// Check a single file for updates without downloading
const status = await manager.isOutdated(local[0].file);

// Update every local ZIM that has a newer catalog version
await manager.updateAll({force: false});

// Fuzzy-search titles across ALL local archives at once
const hits = await manager.search('diabetes treatment', {limit: 10});

// Open a reader by file path OR by catalog name
const reader = await manager.open('wikipedia_en_medicine');
const page = await reader.readPage('A/Diabetes');
await reader.close();

ZimReader

Everything ZimManager does to a single archive is just a thin wrapper around ZimReader. Use it directly when you don't need a whole managed library:

import {ZimReader} from '@ztimson/zim-utils';

const reader = await new ZimReader('./zims/wikipedia_en_medicine.zim').open();

// Metadata (what manager.#readMeta / isOutdated rely on)
const name = await reader.metadata('Name');
const date = await reader.metadata('Date');
const title = await reader.metadata('Title');

// Landing page
const home = await reader.mainPage();

// Direct page lookup by URL
const page = await reader.readPage('A/Diabetes');
console.log(page.mimetype, page.data.toString('utf8'));

// Fuzzy title search within just this archive (what manager.search fans out over)
const results = await reader.search('diabetes,insulin', {limit: 20, htmlOnly: true});

await reader.close();

Catalog

ZimManager.catalog() and its update checks are backed directly by these two functions:

import {zimCatalog, zimCatalogInfo, CATALOG_URL} from '@ztimson/zim-utils';

// Ranked search across the Kiwix catalog (comma-separated terms, like ZimReader.search)
const results = await zimCatalog('history,rome', {lang: 'eng', count: 20, url: CATALOG_URL});

// Exact lookup by catalog `name`, used to check if a local copy is outdated
const entry = await zimCatalogInfo('wikipedia_en_medicine');

License

Copyright © 2026 Zakary Timson | Available under MIT Licensing