veza/apps/web/README.md

Veza Frontend

React + TypeScript frontend application for the Veza audio collaboration platform.

Quick Start

Prerequisites

• Node.js 18+ and npm
• Backend API running (see veza-backend-api/README.md)

Installation

npm install

Development

npm run dev

The application will be available at http://localhost:5173.

Building

npm run build

Setup Steps

1. Environment Variables

Copy .env.example to .env and configure:

# API Configuration
VITE_API_URL=http://localhost:8080/api/v1
VITE_WS_URL=ws://localhost:8081
VITE_STREAM_URL=http://localhost:8082

# Optional: Enable MSW mocks for development
VITE_USE_MSW=0

See .env.example for all available environment variables.

2. Type Generation

TypeScript types are generated from the OpenAPI specification. To regenerate types:

npm run generate:types

This script:

• Reads veza-backend-api/openapi.yaml
• Generates TypeScript types to src/types/generated/
• Creates barrel exports for easy importing

Note: Types are automatically generated in CI/CD before type checking.

3. Validation

Validate types and schemas:

# Type checking
npm run validate:types

# Schema validation
npm run validate:schemas

# Both
npm run validate:all

Available Scripts

Development

• npm run dev - Start development server
• npm run dev:lab - Start with lab environment (real database)
• npm run dev:mocks - Start with MSW mocks enabled

Building

• npm run build - Build for production
• npm run preview - Preview production build

Testing

• npm test - Run unit tests (Vitest)
• npm run test:ui - Run tests with UI
• npm run test:e2e - Run E2E tests (Playwright)

Code Quality

• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint issues
• npm run lint:ui - Run ESLint on src/components and src/features only
• npm run report:arbitrary - Report Tailwind arbitrary values (w-[...], gap-[...], etc.) for migration
• npm run typecheck - Type check without emitting files
• npm run fmt - Format code with Prettier

Type Generation & Validation

• npm run generate:types - Generate TypeScript types from OpenAPI spec
• npm run validate:schemas - Validate Zod schemas
• npm run validate:types - Type check
• npm run validate:all - Run all validations

Project Structure

apps/web/
├── src/
│   ├── components/     # Reusable UI components
│   ├── features/       # Feature modules (auth, tracks, playlists, etc.)
│   ├── hooks/          # Custom React hooks
│   ├── services/       # API clients and services
│   ├── stores/         # Zustand state management (UI state stores)
│   │                   # Note: Feature stores (auth, chat) are in features/*/store/
│   ├── types/          # TypeScript types
│   │   └── generated/  # Auto-generated types from OpenAPI
│   ├── utils/          # Utility functions
│   └── styles/         # Global styles and design tokens
├── e2e/                # End-to-end tests (Playwright)
├── scripts/            # Build and utility scripts
└── public/             # Static assets

Design System

The application uses the Kodo design system. Single source of truth for layout, spacing, shadows, and transitions: docs/DESIGN_TOKENS.md. Shell layout: docs/APP_SHELL.md.

• Colors: Kodo color palette (see src/styles/COLOR_USAGE.md)
• Components: Design system components in src/components/ui/
• Typography: Type scale and hierarchy (see docs/DESIGN_TOKENS.md, src/styles/TYPOGRAPHY_GUIDE.md)
• Spacing: Spacing scale (see docs/SPACING_GUIDE.md) — no arbitrary values (e.g. w-[300px], gap-[7px]) without justification.

Visual regression: npm run visual:capture, npm run visual:compare, npm run visual:update (see visual-tests/README.md). Arbitrary values report: npm run report:arbitrary to list Tailwind arbitrary patterns for migration. New full-layout page: see docs/FULL_LAYOUT_PAGE.md.

ESLint Rules

The project enforces:

• Typography: Use type scale classes (text-xs, text-sm, etc.) instead of arbitrary sizes
• Spacing: Use spacing scale (gap-0 through gap-24) instead of arbitrary values
• Colors: Use Kodo design system colors instead of Tailwind defaults
• Components: Use design system Button component instead of native <button>

See eslint.config.js for full rule configuration.

Contributing

1. Follow the existing code style
2. Run npm run validate:all before committing
3. Ensure all tests pass: npm test
4. Type generation runs automatically in CI/CD

Documentation

• Architecture Guide: docs/ARCHITECTURE.md (MUST READ)
• Component Usage: src/components/COMPONENT_USAGE.md
• Color Usage: src/styles/COLOR_USAGE.md
• Typography: src/styles/TYPOGRAPHY_GUIDE.md
• Spacing: src/styles/SPACING_GUIDE.md

Troubleshooting

Type Generation Fails

Ensure veza-backend-api/openapi.yaml exists and is valid:

cd ../../veza-backend-api
swag init  # Generate OpenAPI spec

Build Errors

1. Clear node_modules and reinstall:

   rm -rf node_modules package-lock.json
   npm install
   

2. Clear Vite cache:

   rm -rf node_modules/.vite
   

Type Errors

Run type generation and validation:

npm run generate:types
npm run validate:types