Development Guide

This guide covers how to set up a local development environment for TuneCamp and start contributing to the project.

Prerequisites

• Node.js: v18 or higher
• FFmpeg: Required for audio processing and waveform generation
• SQLite3: Optional — useful for manual database inspection

Initial Setup

1. Clone the repository:

   git clone https://github.com/scobru/tunecamp.git
   cd tunecamp

2. Install dependencies:

   # Root + backend
   npm install
   
   # Frontend
   cd webapp && npm install && cd ..

3. Configure environment variables: Copy .env.example to .env and fill in the required values (port, JWT secret, music directory path). See the Configuration section in the README for the full variable reference.

Running in Development

You need two terminals running in parallel.

Terminal 1 — backend (TypeScript watch + CSS rebuild):

npm run dev

Terminal 2 — backend server:

npm start

npm run dev only runs tsc --watch and the CSS watcher — it does not start the server. You need npm start (or node dist/index.js) to serve requests.

The server is available at http://localhost:1970 by default (configurable via TUNECAMP_PORT).

Terminal 3 — frontend (Vite dev server with HMR):

cd webapp && npm run dev

The frontend dev server runs at http://localhost:5173 and proxies API requests to the backend.

Running Tests

The project uses Jest for the existing test suite. New modules should use Vitest.

# Run all tests
npm test

# Run a specific test file
npm test src/server/auth.test.ts

Verify no TypeScript errors before opening a PR:

npm run build
cd webapp && npm run build

CLI Tools (src/tools/)

Several maintenance scripts are available under src/tools/:

Script	Command	Purpose
backup.ts	node dist/tools/backup.js ./backups	Creates a timestamped database backup
restore.ts	node dist/tools/restore.js ./backups/tunecamp-<date>.db --force	Restores from a backup
generate-codes.ts	—	Generates unlock codes for releases
relink-tracks.ts	—	Updates audio file paths after moving the library
migrate-dedupe.js	npm run migrate:dedupe	Removes duplicate tracks from the database
migrate-visibility.js	npm run migrate:visibility	Bulk-updates visibility for albums and tracks

See backup-migration.md for more detail on data maintenance.

Code Conventions

• Use TypeScript for all new backend code.
• Follow the existing functional component style in React.
• Document new API endpoints in api-contracts.md.
• Every new database table must be added to src/server/core/database.ts with appropriate indexes.

Contributing

See CONTRIBUTING.md for the full contribution process.