Frontend

This guide will help you get started with contributing to the Opik frontend.

Project Structure

The Opik frontend is a React application located in the apps/opik-frontend directory of the comet-ml/opik repository. It provides the user interface for interacting with the Opik platform.

Directory Layout

apps/opik-frontend/src/
├── api/          # API client and endpoint definitions
├── constants/    # Application-wide constants
├── hooks/        # Shared custom hooks
├── lib/          # Utility libraries
├── store/        # Zustand stores
├── types/        # Shared TypeScript types
├── ui/           # Base UI components (shadcn/ui + Radix)
├── shared/       # Shared business components
├── v1/           # Opik 1 UI (layout, pages, pages-shared)
└── v2/           # Opik 2 UI (layout, pages, pages-shared)

Import rules: ui → shared → v{N}/pages-shared → v{N}/pages (one-way only). v1 and v2 cannot import from each other. Validate with npm run deps:validate.

Setting Up Your Development Environment

We provide multiple ways to develop the frontend. Choose the approach that best fits your workflow:

Best for rapid development with hot reload

This mode runs the frontend as a local process with Vite's dev server, providing instant hot reload when you save files:

Bash

# From repository root - restart everything
scripts/dev-runner.sh

# Or just start (faster if already built)
scripts/dev-runner.sh --start

powershell

# From repository root - restart everything
scripts\dev-runner.ps1

# Or just start (faster if already built)
scripts\dev-runner.ps1 --start

Access the UI at http://localhost:5174 (Vite dev server with hot reload).

Benefits:

Instant hot reload on file changes
Fast rebuilds
Full TypeScript type checking and linting
Easy debugging with browser dev tools

Prerequisites:

Node.js 18+ with npm. You can download it from nodejs.org.
Java Development Kit (JDK) 25 (for backend)
Apache Maven 3.8+ (for backend)

Best for testing the complete system

This mode runs everything in Docker containers:

Bash

# From repository root
./opik.sh --build

# Or start without rebuilding
./opik.sh

powershell

# From repository root
.\opik.ps1 --build

# Or start without rebuilding
.\opik.ps1

Access the UI at http://localhost:5173.

Benefits:

Closest to production environment
No local Node.js installation needed
Consistent environment across team

Prerequisites:

Docker and Docker Compose

Best for understanding the build process

Set up each component manually:

Start backend services: this enables CORS: true in the backend service for local frontend development.
Bash
```
./opik.sh --backend --port-mapping
```

Check that the backend is running: http://localhost:8080/is-alive/ping

Configure environment variables: Update apps/opik-frontend/.env.development:
ini
```
VITE_BASE_URL=/
VITE_BASE_API_URL=http://localhost:8080
```

This tells the frontend development server where to find the backend API.

Install dependencies:
Bash
```
cd apps/opik-frontend
npm install
```
Start the frontend:
Bash
```
npm run start
```

Start backend services: this enables CORS: true in the backend service for local frontend development.
powershell
```
.\opik.ps1 --backend --port-mapping
```

Check that the backend is running: http://localhost:8080/is-alive/ping

Configure environment variables: Update apps\opik-frontend\.env.development:
ini
```
VITE_BASE_URL=/
VITE_BASE_API_URL=http://localhost:8080
```

This tells the frontend development server where to find the backend API.

Install dependencies:
powershell
```
cd apps\opik-frontend
npm install
```
Start the frontend:
powershell
```
npm run start
```

Access the UI at http://localhost:5174.

Prerequisites:

Node.js 18+ with npm. You can download it from nodejs.org.
Docker and Docker Compose (for backend)

For comprehensive documentation on all development modes, troubleshooting, and advanced workflows, see our Local Development Guide.

4. Code Quality Checks

Before submitting a Pull Request, please ensure your code passes the following checks:

Linting

Bash

# From repository root
scripts/dev-runner.sh --lint-fe

powershell

# From repository root
scripts\dev-runner.ps1 --lint-fe

Bash

cd apps/opik-frontend
npm run lint

Type Checking and Unit Tests

Run these commands from the apps/opik-frontend directory:

Bash

cd apps/opik-frontend

npm run typecheck # TypeScript type checking
npm run test      # Unit tests for utilities and helpers

5. Submitting a Pull Request

After implementing, commit your changes and open a Pull Request against the main branch of the comet-ml/opik repository.