Setup & Development

Prerequisites

• Node.js 20+
• npm 10+
• Firebase CLI (npm install -g firebase-tools)

---

Installation

# Clone repository
git clone <repo-url>
cd run-sheet-app

# Install dependencies
npm install

# Copy environment file
cp .env.example .env
# Fill in Firebase credentials in .env

---

Environment Variables

Create a .env file with:

VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_FREESOUND_API_KEY=your_freesound_key  # Optional
VITE_ADMIN_EMAIL=your_admin_email@example.com  # Admin page access (Google Sign-In)

---

Development Server

npm run dev

Opens at http://localhost:5174 with hot module replacement.

---

Production Build

npm run build
npm run preview  # Preview production build locally

---

Deployment

Firebase Hosting

Preview Channel (staging):

npm run deploy:preview

Deploys to https://your-project--preview.web.app

Production (main branch only):

npm run deploy

Includes branch check to prevent accidental production deploys from feature branches.

Cloud Functions

cd functions
npm install
npm run deploy

---

Testing

# Run all unit tests
npm test

# Run with UI
npm run test:ui

# Run E2E tests (Playwright)
npx playwright test

# Run E2E with interactive UI
npx playwright test --ui

# First-time: install Playwright browsers
npx playwright install

Unit tests use Vitest with happy-dom for DOM simulation. E2E tests use Playwright with mobile, iPad, and desktop viewports.

---

Demo Data

On Book Pro includes a pre-built demo project ("The Tempest") for development and testing.

In-App Loading (Frontend)

Load the demo via the Season page in the Admin Portal:

• Click New Production → "Load Demo — The Tempest"
• Creates a real cloud project and hydrates the local Zustand store

Programmatically:

import { loadDemoProject } from '@/demo/load-demo';
import { useAppStore } from '@/store/useAppStore';

loadDemoProject(useAppStore, { onComplete: () => console.log('Loaded!') });

Firestore Seed Script (Backend)

Seed a Firestore project document with demo data across all 8 shards and 4 subcollections:

cd functions
npx ts-node src/debug/seed-demo-project.ts

Prerequisites:

• Application Default Credentials (gcloud auth application-default login)
• Or set GOOGLE_APPLICATION_CREDENTIALS to a service account key file
• Edit the PROJECT_ID constant in the script to target the desired Firestore project document

Data Module

File	Purpose
src/demo/tempest-demo-data.ts	All demo constants (personnel, characters, props, etc.)
src/demo/load-demo.ts	loadDemoProject() — hydrates Zustand store
functions/src/debug/seed-demo-project.ts	Admin SDK script for Firestore seeding

---

Contributing

Branch Strategy

• main — Production-ready code
• testing — Pre-merge verification branch
• Feature branches — feature/your-feature-name

Pull Request Checklist

• [ ] Code follows style guide
• [ ] Tests pass
• [ ] Documentation updated
• [ ] No lint errors
• [ ] Branch is up to date with target branch

---

Scripts Reference

Script	Description
npm run dev	Start development server
npm run build	Production build
npm run preview	Preview production build
npm run deploy	Deploy to Firebase (main only)
npm run deploy:preview	Deploy to preview channel
npm test	Run unit tests
npm run test:ui	Run tests with UI
npx playwright test	Run E2E tests
npx playwright test --ui	Run E2E tests with interactive UI