Contributing to the 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:

$
# From repository root - restart everything
$
scripts/dev-runner.sh
$
$
# Or just start (faster if already built)
$
scripts/dev-runner.sh --start

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

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

Type Checking and Unit Tests

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

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