upstream-mattermost/webapp/CLAUDE.OPTIONAL.md

# CLAUDE.md

Guidance for Claude Code when working inside `webapp/`.

## Project Overview

This is the Mattermost web app codebase, a React-based frontend application for the Mattermost collaboration platform. The repository is structured as an npm workspace monorepo with multiple packages, with the main application code in the `channels` package and shared platform code in `platform/*` packages.

- **Primary workspace**: `channels/` (UI, Redux, routing).
- **Shared packages**: `platform/*`.
- **Scripts**: `webapp/scripts/` power dev server, builds, and localization flows.
- **Coding Standards**: Read `webapp/STYLE_GUIDE.md` for canonical standards; nested `CLAUDE.md` files cover directory-specific rules.

## Core Commands

| Task | Command |
| --- | --- |
| Install deps | `npm install` (includes postinstall build of platform packages) |
| Dev server (prod build watch) | `make run` |
| Dev server (webpack-dev-server) | `make dev` or `npm run dev-server --workspace=channels` |
| Build all workspaces | `make dist` or `npm run build` |
| Build Channels only | `npm run build --workspace=channels` |
| Tests | `make test` or `npm run test --workspace=channels` (use `test:watch`, `test:updatesnapshot` as needed) |
| Lint / Style | `make check-style`, `make fix-style`, `npm run check --workspace=channels`, `npm run fix --workspace=channels` |
| Type check | `make check-types` |
| Clean artifacts | `make clean` or `npm run clean --workspaces --if-present` |

## Top-Level Directory Map

- `channels/` – Channels workspace. See `channels/CLAUDE.md`.
  - `src/` – App source with further scoped guides (components, actions, selectors, reducers, store, sass, i18n, tests, utils, types, plugins, packages/mattermost-redux).
- `platform/` – Shared packages (`client`, `components`, `types`, `eslint-plugin`). See `platform/CLAUDE.md` plus sub-guides.
- `scripts/` – Build/dev automation. See `scripts/CLAUDE.md`.
- `STYLE_GUIDE.md` – Authoritative style + accessibility + testing reference.
- `README.md`, `config.mk`, `Makefile` – onboarding, env config, and command wiring.

## Workspace Architecture

This repository uses npm workspaces:

- **channels** (`channels/`): Main Mattermost web app containing all UI components, Redux logic, and application code
- **@mattermost/types** (`platform/types/`): TypeScript type definitions
- **@mattermost/client** (`platform/client/`): REST and WebSocket client for the Mattermost API
- **@mattermost/components** (`platform/components/`): Shared React components
- **@mattermost/shared** (`platform/shared/`): Cross-product components and utilities used by the web app and plugins (e.g. `Button`, `WithTooltip`). Prefer these over hand-rolled equivalents.
- **@mattermost/eslint-plugin** (`platform/eslint-plugin/`): Custom ESLint rules

### Importing Packages

Always import packages using their full name, never relative paths:
```typescript
// Correct
import {Client4} from '@mattermost/client';
import {UserProfile} from '@mattermost/types/users';
import {Button} from '@mattermost/shared/components/button';
import {WithTooltip} from '@mattermost/shared/components/tooltip';
import {getUser} from 'mattermost-redux/selectors/entities/users';

// Incorrect
import Client4 from '../platform/client/src/client4.ts';
```

## Key Dependencies

- **React 18.2**: Main UI framework
- **Redux 5.0**: State management
- **React Router 5.3**: Client-side routing
- **React Intl**: Internationalization
- **Floating UI**: Tooltips and popovers (prefer `WithTooltip` from `@mattermost/shared/components/tooltip`)
- **@mattermost/shared**: Shared components and utilities (`Button`, `WithTooltip`, etc.) — prefer these over rolling your own
- **@mattermost/compass-icons**: Icon library (prefer over font-awesome)
- **Monaco Editor**: Code editor integration
- **Styled Components**: Limited use (for MUI and some legacy components)

## Important Configuration Files

- `channels/webpack.config.js`: Webpack configuration with module federation
- `channels/jest.config.js`: Jest test configuration
- `channels/tsconfig.json`: TypeScript configuration with workspace references
- `channels/.eslintrc.json`: ESLint configuration

## Cross-Cutting Standards & Common Gotchas

- **Functional Components**: Prefer functional React components with hooks; memoize expensive logic.
- **Data Access**: Client4/WebSocket access happens via Redux actions only—never directly from components.
- **Internationalization**: All UI strings must be translatable via React Intl. Use `FormattedMessage` unless a raw string is required. When adding or modifying a new translatable string, add or modify ONLY the English main file `en.json`. DO NOT update the other languages.
- **Styling**: Uses SCSS + CSS variables with BEM naming; avoid `!important` unless migrating legacy code.
- **Testing**: RTL + `userEvent` for tests; no snapshots. Use helpers under `channels/src/tests/`.
- **Accessibility**: Follow guidance in `STYLE_GUIDE.md` (semantic elements, keyboard support, focus management).
- **Platform Packages**: Rebuild automatically on `npm install`; re-run if types appear stale.
- **Adding Dependencies**: Always add dependencies with `npm add <pkg> --workspace=channels` (or the relevant workspace).
- **Redux State Split**: `state.entities.*` (server data via mattermost-redux) vs `state.views.*` (UI/persisted). Store new server entities in mattermost-redux first.
- **Client4 Returns**: Methods return `{response, headers, data}` – unwrap accordingly in actions.

## Nested CLAUDE Files

- Channels workspace: `channels/CLAUDE.md`, `channels/src/CLAUDE.md`.
- Channels source subfolders: `components/`, `actions/`, `selectors/`, `reducers/`, `store/`, `sass/`, `i18n/`, `tests/`, `utils/`, `types/`, `plugins/`, `packages/mattermost-redux/`.
- Platform packages: `platform/CLAUDE.md`, plus `platform/client/`, `platform/components/`, `platform/shared/`, `platform/types/`.
- Tooling: `scripts/CLAUDE.md`.

Use these nested guides for focused, actionable instructions when working within each directory.