# NPM Packages: Frontend (claw-frontend)

The frontend is a Next.js 16 application with React 19, using TanStack Query for server state, Zustand for client state, and shadcn/ui for components.

## Core Framework

| Package      | Version  | Purpose                                    |
| ------------ | -------- | ------------------------------------------ |
| `next`       | ^16.2.2  | React meta-framework (App Router, SSR)     |
| `react`      | ^19.2.4  | UI component library                       |
| `react-dom`  | ^19.2.4  | React DOM renderer                         |

### Next.js Configuration

- Dev server uses Turbopack (`next dev --turbopack`) on port 3000
- Production build uses Webpack (`next build --webpack`)
- App Router with `src/app/(portal)/` layout group
- All pages are client-rendered (no SSR for the portal)

## State Management

| Package               | Version  | Purpose                                  |
| --------------------- | -------- | ---------------------------------------- |
| `@tanstack/react-query` | ^5.62.0 | Server state management (queries + mutations) |
| `zustand`             | ^5.0.2   | Minimal client state (auth, sidebar, filters) |

### TanStack Query Usage

- All GET requests use `useQuery` wrapped in custom hooks
- All POST/PATCH/DELETE use `useMutation` with `onSuccess` invalidation
- Query key factory at `src/repositories/shared/query-keys.ts`
- Never call `useQuery`/`useMutation` directly in TSX files

### Zustand Stores

- `auth.store.ts` -- current user, tokens, login/logout actions
- `sidebar.store.ts` -- sidebar open/close state
- `log-filters.store.ts` -- observability page filter state

## UI Components

| Package                       | Version  | Purpose                          |
| ----------------------------- | -------- | -------------------------------- |
| `@radix-ui/react-avatar`     | ^1.1.2   | Avatar primitive                 |
| `@radix-ui/react-dialog`     | ^1.1.4   | Modal/dialog primitive           |
| `@radix-ui/react-dropdown-menu` | ^2.1.4 | Dropdown menu primitive          |
| `@radix-ui/react-progress`   | ^1.1.8   | Progress bar primitive           |
| `@radix-ui/react-select`     | ^2.1.4   | Select dropdown primitive        |
| `@radix-ui/react-separator`  | ^1.1.1   | Visual separator                 |
| `@radix-ui/react-slot`       | ^1.1.1   | Polymorphic slot component       |
| `@radix-ui/react-toast`      | ^1.2.4   | Toast notification primitive     |
| `lucide-react`               | ^0.468.0 | Icon library (tree-shakeable)    |
| `class-variance-authority`   | ^0.7.1   | Variant-based component styling  |
| `clsx`                       | ^2.1.1   | Conditional className utility    |
| `tailwind-merge`             | ^2.6.0   | Tailwind class conflict resolver |
| `tailwindcss-animate`        | ^1.0.7   | Animation utility classes        |
| `next-themes`                | ^0.4.6   | Theme switching (dark/light/system) |

### shadcn/ui Pattern

Components in `src/components/ui/` are auto-generated by shadcn/ui CLI. They use Radix primitives + Tailwind + CVA for styling. These files should not be manually edited.

## Forms and Validation

| Package                | Version  | Purpose                           |
| ---------------------- | -------- | --------------------------------- |
| `react-hook-form`      | ^7.54.2  | Form state management             |
| `@hookform/resolvers`  | ^3.9.1   | Zod resolver for react-hook-form  |
| `zod`                  | ^3.24.1  | Schema validation                 |

## Content Rendering

| Package            | Version  | Purpose                              |
| ------------------ | -------- | ------------------------------------ |
| `react-markdown`   | ^10.1.0  | Markdown rendering in messages       |
| `rehype-highlight` | ^7.0.2   | Syntax highlighting in code blocks   |
| `remark-gfm`       | ^4.0.1   | GitHub Flavored Markdown support     |

## HTTP Client

| Package | Version  | Purpose                                  |
| ------- | -------- | ---------------------------------------- |
| `axios` | ^1.14.0  | HTTP client with interceptors            |

### Axios Configuration

- Base instance at `src/lib/http-client.ts`
- Request interceptor adds `Authorization: Bearer {token}` header
- Response interceptor handles 401 -> token refresh -> retry
- `X-Request-ID` header added to every request for correlation

## Virtualization

| Package          | Version  | Purpose                            |
| ---------------- | -------- | ---------------------------------- |
| `react-virtuoso` | ^4.18.4  | Virtualized list rendering         |

Used for chat message lists to handle threads with thousands of messages efficiently.

## Dev Dependencies

| Package                        | Version  | Purpose                         |
| ------------------------------ | -------- | ------------------------------- |
| `typescript`                   | ^5.7.2   | TypeScript compiler             |
| `vitest`                       | ^3.2.4   | Test runner (replaces Jest)     |
| `@testing-library/react`      | ^16.3.2  | React component testing         |
| `@testing-library/jest-dom`   | ^6.9.1   | DOM assertion matchers          |
| `@testing-library/user-event` | ^14.6.1  | User interaction simulation     |
| `@testing-library/dom`        | ^10.4.1  | DOM testing utilities           |
| `@vitejs/plugin-react`        | ^6.0.1   | Vite React plugin for Vitest    |
| `jsdom`                       | ^25.0.1  | DOM environment for tests       |
| `@playwright/test`            | ^1.49.1  | E2E browser testing             |
| `tailwindcss`                 | ^3.4.17  | CSS utility framework           |
| `postcss`                     | ^8.4.49  | CSS processing pipeline         |
| `autoprefixer`                | ^10.4.20 | CSS vendor prefix automation    |
| `prettier-plugin-tailwindcss` | ^0.6.9   | Tailwind class sorting          |
| `eslint`                      | ^9.17.0  | Linter                          |
| `eslint-config-next`          | ^16.2.3  | Next.js ESLint rules            |
| `eslint-plugin-import-x`     | ^4.5.0   | Import validation               |
| `eslint-plugin-react-hooks`  | ^5.2.0   | React hooks rules               |
| `eslint-plugin-security`     | ^3.0.1   | Security lint rules             |
| `eslint-plugin-unicorn`      | ^56.0.1  | Best practice rules             |
