Skip to content

About

Tracks Modrinth mods and modpacks, detects changes, and streams live updates to the browser over WebSockets

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ModTracker

ModTracker watches Modrinth mods and modpacks, records what changes, and pushes live updates to the browser over WebSockets.

Features

  • Project sync: Imports mods and modpacks from the Modrinth API into a local SQLite database (POST /api/sync, POST /api/sync/modpacks).
  • Background polling worker: A separate process (npm run worker:poll) polls due projects in batches of 10, reschedules each one by a priority score, and backs off on failures.
  • Change detection: Detects new version releases, title/description/category/loader changes, and download milestones (1K to 10M), each with a summary and an impact score.
  • Update feed: Paginated history of detected changes, filterable by project, change type, and date (GET /api/updates).
  • Live updates: Browser clients connect to a WebSocket endpoint (/_ws) and receive updates as they are detected. The dashboard shows connection status and reconnects automatically.
  • Search and browsing: Filter and sort tracked projects, view project detail pages, and query Modrinth directly through /api/search.
  • Modpack analysis: List a modpack's mods, compare two modpacks, find modpacks that contain a given mod, and list trending, new, or recently updated modpacks.
  • Dashboard stats: Project totals and recent update counts (GET /api/stats).

Tech stack

  • Nuxt 3 (Nitro server with file-based API routes and a WebSocket route) and Vue 3
  • Nuxt UI 3 for components
  • TypeScript
  • Drizzle ORM on SQLite (better-sqlite3, WAL mode), with drizzle-kit for schema management
  • consola for logging
  • Vitest for unit tests

Architecture

  • API routes: server/api/ exposes projects, search, modpacks, trending, updates, stats, and sync endpoints. Modrinth access is shared through server/utils/.
  • Modrinth client: server/utils/modrinth-api.ts applies a client-side token-bucket rate limiter, retries failed requests, and honors Retry-After on HTTP 429.
  • Poller worker: server/workers/poller.ts runs as a standalone Node process. Each cycle it loads up to 10 projects due in polling_schedule, fetches fresh data from Modrinth, stores changes, and reschedules each project. Failures back off by 1.5x per attempt, capped at 10x.
  • Change detection: server/utils/change-detector.ts compares the stored project with fresh data and produces typed events (version release, metadata change, download milestone) with impact scores.
  • WebSocket hub: server/utils/ws-hub.ts tracks connected clients in memory and fans out updates on subscribed channels. The worker is a separate process, so it sends updates to the internal endpoint POST /api/_internal/broadcast (authenticated with a shared-secret header), and the hub relays them to clients on /_ws.
  • Database: The Drizzle schema lives in server/database/schema.ts. The app actively uses four tables: projects, versions, update_history, and polling_schedule. The schema also defines placeholder tables for users, follows, alerts, dependencies, modpack contents, search cache, and trending snapshots that are not wired up yet.

Getting started

Requirements: Node.js and Bun (the repo ships a bun.lock; npm install also works).

git clone https://github.com/bbauti/modtracker.git
cd modtracker
bun install
cp .env.example .env
mkdir -p data
npm run db:push     # creates the SQLite schema in ./data
npm run dev         # Nuxt dev server at http://localhost:3000

In a second terminal, start the polling worker:

npm run worker:poll

Then click Sync Projects on the dashboard, or trigger a sync from the command line:

curl -X POST http://localhost:3000/api/sync \
  -H 'Content-Type: application/json' \
  -d '{"projectType":"mod","limit":20}'

Environment variables

Copy .env.example to .env and adjust the values as needed.

Variable Purpose Default
DATABASE_URL SQLite database file file:./data/modtracker.db
INTERNAL_SECRET Shared secret for the worker-to-server broadcast call. Required for live updates; set a random value. none
SERVER_URL Where the worker sends broadcasts http://localhost:3000
WS_URL WebSocket URL the browser connects to ws://localhost:3000/_ws

The worker reads environment variables from its own shell and does not load .env, so export INTERNAL_SECRET and SERVER_URL in that shell too if you change them.

Scripts

Command What it does
npm run dev Start the Nuxt dev server
npm run build / npm run preview Build for production and preview the build
npm run worker:poll Start the background polling worker
npm run db:push Apply the Drizzle schema to the database
npm run db:studio Open Drizzle Studio

Tests

npm run test:run   # single run
npm test           # watch mode

Three unit-test suites in tests/unit/ cover the Modrinth API client, the search service, and the modpack analyzer. They mock fetch and the Modrinth API module, so they never call the live API.

About

Tracks Modrinth mods and modpacks, detects changes, and streams live updates to the browser over WebSockets

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages