> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.

# Frontend

# Contributing to the Frontend

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

> **Tip**
>
> Before you start, please review our general [Contribution Overview](/contributing/overview) and the [Contributor License Agreement (CLA)](https://github.com/comet-ml/opik/blob/main/CLA.md).

## 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:

#### Local Process Mode (Recommended)

**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:

#### Linux/Mac

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

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

#### Windows

```powershell wordWrap
# 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](https://nodejs.org/).
* Java Development Kit (JDK) 25 (for backend)
* Apache Maven 3.8+ (for backend)

#### Docker Mode

**Best for testing the complete system**

This mode runs everything in Docker containers:

#### Linux/Mac

```bash wordWrap
# From repository root
./opik.sh --build

# Or start without rebuilding
./opik.sh
```

#### Windows

```powershell wordWrap
# 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

#### Manual Setup

**Best for understanding the build process**

Set up each component manually:

#### Linux/Mac

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

Check that the backend is running: [http://localhost:8080/is-alive/ping](http://localhost:8080/is-alive/ping)

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

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

3. **Install dependencies:**
   ```bash wordWrap
   cd apps/opik-frontend
   npm install
   ```

4. **Start the frontend:**
   ```bash wordWrap
   npm run start
   ```

#### Windows

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

Check that the backend is running: [http://localhost:8080/is-alive/ping](http://localhost:8080/is-alive/ping)

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

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

3. **Install dependencies:**
   ```powershell wordWrap
   cd apps\opik-frontend
   npm install
   ```

4. **Start the frontend:**
   ```powershell wordWrap
   npm run start
   ```

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

**Prerequisites:**

* Node.js 18+ with npm. You can download it from [nodejs.org](https://nodejs.org/).
* Docker and Docker Compose (for backend)

For comprehensive documentation on all development modes, troubleshooting, and advanced workflows, see our [Local Development Guide](/contributing/guides/local-development).

### 4. Code Quality Checks

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

#### Linting

#### Using dev-runner (Recommended)

#### Linux/Mac

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

#### Windows

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

#### Manual npm

```bash wordWrap
cd apps/opik-frontend
npm run lint
```

#### Type Checking and Unit Tests

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

```bash wordWrap
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.