# 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).
</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.

## 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](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](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](/contributing/guides/local-development).

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