Development

How to run hdtracker from the source code – for trying out changes or contributing.

What you need

• Node.js 24 (the version the Docker image uses)
• Git
• The same API keys as for a normal installation – see Installation

Run it locally

git clone https://github.com/dvnkln/hdtracker.git
cd hdtracker
npm install
cp .env.example .env

Fill in .env as described in Installation (ORIGIN is not needed for the development server). Then start it:

npm run dev

Open http://localhost:5173. Changes to the code show up right away. The database and backups are stored in the data folder inside the project.

Useful commands

Command	What it does
npm run dev	Development server with live reload
npm run check	Type check
npm test	Automatic tests (each test file gets its own empty database; no request leaves your machine)
npm run test:e2e	Browser tests of the main flows with made-up data (needs npx playwright install chromium once)
npm run format	Format the code with Prettier (npm run lint only checks)
npm run build then node --env-file=.env start.js	Build and run the production version (port 3000; needs ORIGIN=http://localhost:3000 in .env)
npm run db:generate	Create a new database migration after changing the schema

Build the Docker image from source

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

This builds the image from your working copy instead of pulling the published one.

How the project is built

SvelteKit (Node adapter, Svelte 5), TypeScript, Drizzle ORM with SQLite (better-sqlite3) and Tailwind CSS.

• Database changes only through new migrations in drizzle/ that keep existing data – they run automatically on start. Never edit or delete an existing migration.
• Texts shown in the app live in src/lib/i18n/en.ts and de.ts; both files need the same entries.
• Server-only code (database, API clients, background tasks) lives in src/lib/server/.

Found a bug or have an idea? Open an issue.