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](/v1/contributing/overview) and the [Contributor License Agreement (CLA)](https://github.com/comet-ml/opik/blob/main/CLA.md). </Tip>

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:

<Tabs> <Tab value="Local Process Mode" title="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:

<Tabs>
  <Tab title="Linux/Mac">
    ```bash
    # From repository root - restart everything
    scripts/dev-runner.sh

    # Or just start (faster if already built)
    scripts/dev-runner.sh --start
    ```
  </Tab>
  <Tab title="Windows">
    ```powershell
    # From repository root - restart everything
    scripts\dev-runner.ps1

    # Or just start (faster if already built)
    scripts\dev-runner.ps1 --start
    ```
  </Tab>
</Tabs>

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) 21 (for backend)
- Apache Maven 3.8+ (for backend)

</Tab> <Tab value="Docker Mode" title="Docker Mode"> **Best for testing the complete system**

This mode runs everything in Docker containers:

<Tabs>
  <Tab title="Linux/Mac">
    ```bash
    # From repository root
    ./opik.sh --build

    # Or start without rebuilding
    ./opik.sh
    ```
  </Tab>
  <Tab title="Windows">
    ```powershell
    # From repository root
    .\opik.ps1 --build

    # Or start without rebuilding
    .\opik.ps1
    ```
  </Tab>
</Tabs>

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

</Tab> <Tab value="Manual Setup" title="Manual Setup"> **Best for understanding the build process**

Set up each component manually:

<Tabs>
  <Tab title="Linux/Mac">
    1. **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

    2. **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.

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

    4. **Start the frontend:**
       ```bash
       npm run start
       ```
  </Tab>
  <Tab title="Windows">
    1. **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

    2. **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.

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

    4. **Start the frontend:**
       ```powershell
       npm run start
       ```
  </Tab>
</Tabs>

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)

</Tab> </Tabs>

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

<Tabs> <Tab value="Using dev-runner" title="Using dev-runner (Recommended)"> <Tabs> <Tab title="Linux/Mac"> ```bash # From repository root scripts/dev-runner.sh --lint-fe ``` </Tab> <Tab title="Windows"> ```powershell # From repository root scripts\dev-runner.ps1 --lint-fe ``` </Tab> </Tabs> </Tab> <Tab value="Manual npm" title="Manual npm"> ```bash cd apps/opik-frontend npm run lint ``` </Tab> </Tabs>

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.