Development Setup

Follow this guide to set up your local development environment for the dicechess-analytics-ui repository.

Prerequisites

Ensure you have the following installed on your system:

• Node.js (v26 or later, as defined in mise.toml)
• Mise (highly recommended task runner, or run the raw npm commands)
• GitHub CLI (gh) (logged in to GitHub to retrieve packages token)

---

1. Authentication & Package Access

The SvelteKit application depends on @rabestro/dicechess-engine, which is published in the GitHub Packages npm registry.

Even for public packages, GitHub requires authentication for downloads. In .npmrc, the registry token is mapped to the NODE_AUTH_TOKEN environment variable.

Before running dependency installation commands, export your GitHub CLI authentication token:

export NODE_AUTH_TOKEN=$(gh auth token)

[!TIP] If you are using mise, these environment variables can be automated in mise.local.toml or set dynamically.

---

2. Installing Dependencies

Install the workspace dependencies using standard npm:

# Using Mise (installs app dependencies AND docs dependencies)
mise run setup

# Or manually running npm commands:
npm install
npm --prefix docs install

---

3. Development Server

Start the Vite development server:

# Using Mise
mise run dev

# Or manually
npm run dev

• Vite Dev Server URL: http://localhost:5173
• API Proxy: Any requests matching /api/* are automatically proxied to the backend at http://localhost:8000. Make sure dicechess-analytics is running locally (using mise run db:up and starting the scala backend).

---

4. Environment Variables

Create a .env or .env.local file at the root of the project to customize the application behavior:

Variable	Default	Purpose
VITE_API_URL	/api	The base URL for the backend API endpoints.
VITE_MOCK_AUTH	false	When set to true, bypasses OAuth auth gate for local development or E2E tests.

---

5. Deployment & Production Build

The application compiles into a static single-page application (SPA):

# Compile the app
mise run compile  # Runs "npm run build"

The output assets are written to the dist/ directory. In production, this directory is copied into a Docker image and served by Nginx (defined in Dockerfile and nginx.conf).