102 lines
5.9 KiB
Markdown
102 lines
5.9 KiB
Markdown
# 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.
|