# Frontend Guide

The user-facing site lives in `frontend/` and is built with Next.js 16, React
19, TypeScript, Tailwind CSS, and TanStack Query.

## Key Files And Areas

- `frontend/src/app/**`: App Router pages and route handlers
- `frontend/src/components/**`: reusable UI and feature components
- `frontend/src/components/labs/hook.ts`: lab data fetching hooks
- `frontend/src/components/web-console/controller.ts`: xterm.js controller for
  browser terminal sessions
- `frontend/next.config.ts`: framework and observability config
- `frontend/src/app/api/[[...fallback_placeholder]]/route.ts`: local `/api/*`
  proxy behavior

## Local Development

### Prerequisites

- Node `v22.13.0` via `frontend/.nvmrc`
- `pnpm@9.15.1`

### Install And Run

```bash
cd frontend
corepack pnpm install --frozen-lockfile
pnpm dev
```

## API Modes

`frontend/src/lib/api/base.ts` uses `API_BASE` first on the server and falls
back to `NEXT_PUBLIC_API_BASE`.

- Remote backend mode:
  - `API_BASE=https://labs.tidb.io/api`
  - `NEXT_PUBLIC_API_BASE=/api`
  - Local Next `/api/*` requests are proxied to the hosted backend by
    `frontend/src/app/api/[[...fallback_placeholder]]/route.ts`
- Local backend mode:
  - Set `NEXT_PUBLIC_API_BASE` to a full local URL such as
    `http://127.0.0.1:8000/api`

Known caveat:

- The local Next `/api/*` proxy currently forwards to the production API. For
  local backend work, bypass it with a full `NEXT_PUBLIC_API_BASE`.

## Validation

```bash
cd frontend
pnpm run ts-check
pnpm run test
pnpm run lint
pnpm run i18n:check
```

## Frontend Working Notes

- Preserve the established visual language unless the task is explicitly a
  redesign.
- Keep API-mode assumptions explicit in docs and PRs because the frontend can
  talk either to local Django or the hosted backend.
- Treat web-console flows as cross-service work because they depend on backend
  URL signing and `ssh-proxy`.