Local Development Setup¶

This guide covers setting up Peek for local development with hot reloading and debugging capabilities.

Prerequisites¶

Node.js 18+ (20+ recommended)
Docker and Docker Compose
Git
A running Stash server with GraphQL API enabled

Quick Start (Docker Compose)¶

The fastest way to get a development environment running:

Clone the repository:

git clone https://github.com/carrotwaxr/peek-stash-browser.git
cd peek-stash-browser

Set up environment:
```
cp .env.example .env
```

Configure .env:

JWT_SECRET=your-dev-secret-here
DATABASE_URL=file:./data/peek-stash-browser.db

Start the development stack:
```
docker-compose up -d
```
Access the app: Open http://localhost:6969
Complete the Setup Wizard to connect to your Stash server

Development Ports¶

Port	Service	Description
`6969`	Frontend UI	Vite dev server with hot reloading
`8000`	Backend API	Express server (internal Docker network)

Native Development (Without Docker)¶

For faster iteration and debugging, you can run the frontend and backend natively.

Backend Setup¶

cd server
npm install
npx prisma generate
npx prisma migrate dev
npm run dev

The backend runs on http://localhost:8000.

Frontend Setup¶

cd client
npm install
npm run dev

The frontend runs on http://localhost:6969 with hot module replacement (HMR).

Environment Variables¶

Create a .env file in the server/ directory:

# Required
JWT_SECRET=dev-secret-change-in-production
DATABASE_URL=file:./data/peek-db.db

# Optional
NODE_ENV=development
LOG_LEVEL=debug

Database Management¶

Peek uses SQLite with Prisma ORM.

View Database¶

cd server
npx prisma studio

Opens a web UI at http://localhost:5555 to browse and edit data.

Reset Database¶

cd server
rm -rf data/peek-db.db
npx prisma migrate dev

Generate Prisma Client¶

After schema changes:

cd server
npx prisma generate

Create Migration¶

After modifying prisma/schema.prisma:

cd server
npx prisma migrate dev --name your_migration_name

Testing¶

Run Backend Tests¶

cd server
npm test

Run Frontend Tests¶

cd client
npm test

Integration Tests¶

Integration tests require a running Stash server. See the Regression Testing Guide for details.

Debugging¶

Backend Debugging (VS Code)¶

Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Backend",
      "skipFiles": ["<node_internals>/**"],
      "cwd": "${workspaceFolder}/server",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "console": "integratedTerminal"
    }
  ]
}

Frontend Debugging¶

Use browser DevTools (F12). The Vite dev server provides source maps for debugging TypeScript/React code.

View Logs¶

# Docker Compose logs
docker-compose logs -f

# Backend only
docker-compose logs -f peek-server

# Frontend only
docker-compose logs -f peek-client

Code Style¶

The project uses ESLint and Prettier for code formatting.

Format Code¶

# Root (runs on all packages)
npm run format

# Or in specific directory
cd client && npm run format
cd server && npm run format

Lint Check¶

npm run lint

Building for Production¶

Build Docker Image¶

docker build -t peek-stash-browser:local .

Test Production Build Locally¶

docker run -d \
  --name peek-local-test \
  -p 6969:80 \
  -v peek-test-data:/app/data \
  -e JWT_SECRET=test-secret \
  peek-stash-browser:local

Troubleshooting¶

Port Already in Use¶

# Find process using port 6969
lsof -i :6969

# Kill it
kill -9 <PID>

Prisma Client Out of Sync¶

cd server
npx prisma generate

Docker Compose Issues¶

# Rebuild containers
docker-compose down
docker-compose build --no-cache
docker-compose up -d

Clear Node Modules¶

rm -rf node_modules client/node_modules server/node_modules
npm install
cd client && npm install
cd ../server && npm install

Next Steps¶

Technical Overview - Understand the architecture
Sync Architecture - How Stash sync works
API Reference - Backend API documentation