oncall-engine/dev/frontend_guidelines.md

# OnCall Frontend Guidelines

The base guidelines we decided to follow are:

- <https://github.com/ryanmcdermott/clean-code-javascript>
- <https://github.com/grafana/grafana/tree/main/contribute/style-guides>

Anything that is either not covered by the materials above or we decided to do differently is stated in this document.

## Ways of working

### Code reviews

- PR can be merged when the following conditions are met:
  - CI pipeline succeeded without bypassing checks
  - There is at least 1 approval from the frontend team and no opened remarks from reviewers other than the approver
  - All comments are replied, answered, addressed or discussed separately
  - We make use of builtin GH PR reviews
  - Minor comments that don’t need to be addressed right away and are not a blocker for a merge
are marked with “Minor: “ prefix
  - *Unless there is some important hotfix to make and no frontend mates are available*

## Technical conventions

### Type-safety

- Don’t use implicit / explicit `any` or @ts-ignore

### Use auto generated types for new features

- For new features and endpoints that are covered by OpenApi schemas, we should use auto generated types and
typed http client

### Naming conventions on most used variables such as handlers, booleans etc

- Use descriptive naming (such as the use of is) that follows natural convention such as `isFormVerified`
or `isAuthenticated` instead of *verified*, *authenticated* etc
- Use descriptive naming for event handlers such as `onIconClick` or `onInputChange` rather than *handleChange*
- Include the **verb** part in the functions’ names
- For **3 or more** function arguments use object destructuring
<https://github.com/ryanmcdermott/clean-code-javascript?tab=readme-ov-file#function-arguments-2-or-fewer-ideally>
- For functions that return other functions getBlaBlaHandler (in case of handlers) or getBlaBlaFn
(if it’s not handler that is returned)
- Don’t use higher-ordered functions without clear need

## State management

### Don’t use returned values from MobX actions

- MobX actions should not return value that is later used within components. Instead MobX actions should update
observables and then components should consume observables to reflect data updates.

### Leverage small global stores over local state passed as props over multiple levels

- Create small specialized store in MobX even for small feature
instead of relying on local state that is passed down the React tree over multiple levels
e.g.:
  alert_receive_channel_connected_channels.ts
  alert_receive_channel_webhooks.ts

### Use global decorators / custom hooks / utilities consistently

- For example:
  - `@WithGlobalNotification` to set successful / failing notification based on MobX action’s result
  - `@AutoLoadingState` to manage loading statuses of async actions
  - `useIsLoading` to consume loading state
  - `useDrawer` to manage drawers
  - `useConfirmModal` to manage confirm modal
  - Global helpers

## Code organization

### Store files in appropriate places

- Store files in appropriate places (components, containers, models etc)
- Helpers and configs should be stored in the same folder with the appropriate name
e.g. [container].helper.ts, [container].config.ts
- Project-wide utilities should be placed in the **utils** folder`
- Use named exports for all code you want to export from a file.
- Export only the code that is meant to be used outside the module.

### Don’t opt-out from eslint / TS rules

- Avoid opting out from eslint or TS rules unless there is a strong reason / lack of possibility to follow the rule

## Styling

### Use Emotion.js with agreed code style

- Use emotion.js for styling
- Make use of `useStyles2` hook
- Use css `` syntax
- Place `getStyles` function at the end of the same file or in the separate file with `X.styles.ts` suffix
(if it’s reused by multiple components or it’s too large for placing in the same component’s file)

## React

### Keep components functional and small

- Use functional components for new features
- Leverage components composition, use many small components, render list items in dedicated component
and dereference values late
<https://mobx.js.org/react-optimizations.html>
- Keep components small and flat
- Use dedicated components over render functions in case a there's a risk that a single component grows too much
- Static values (especially non-primitive) that don’t depend on local state, props or store should be extracted
out of component
- Don’t create unnecessary local state that duplicates parts of global store
- Leverage custom hooks to extract repetitive logic
- Don’t use useMemo / useCallback by default

## Architecture

### Use layered architecture

- Don’t interact with backend directly from components
- Don’t interact with 3rd party (faro, web storage etc) directly but rather through service

## Frontend-backend communication

### Use typed HTTP request and response payloads

- HTTP request payload and response payload should always be typed
- Use typed http client whenever we have auto-generated types available