ModTracker watches Modrinth mods and modpacks, records what changes, and pushes live updates to the browser over WebSockets.
- 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).
- 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
- API routes:
server/api/exposes projects, search, modpacks, trending, updates, stats, and sync endpoints. Modrinth access is shared throughserver/utils/. - Modrinth client:
server/utils/modrinth-api.tsapplies a client-side token-bucket rate limiter, retries failed requests, and honorsRetry-Afteron HTTP 429. - Poller worker:
server/workers/poller.tsruns as a standalone Node process. Each cycle it loads up to 10 projects due inpolling_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.tscompares 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.tstracks connected clients in memory and fans out updates on subscribed channels. The worker is a separate process, so it sends updates to the internal endpointPOST /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, andpolling_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.
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:3000In a second terminal, start the polling worker:
npm run worker:pollThen 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}'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.
| 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 |
npm run test:run # single run
npm test # watch modeThree 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.