Frontend

Development Setup

  • Use a Tailwind CSS linter (code plugin) if you write CSS
  • Use Storybook to develop components

Source Code Best Practices

We use Bulletproof React with following specialisations/exceptions:

  • We use camelCase in file names and identifiers.
  • We use absolute imports.
  • We use minimal number of packages: need to be noted in solutions or in a decision
  • Be thoughtful of memory consumption and runtime
  • Use debounce hook as in PlantingAttributeEditForm.tsx
  • Use react-query correctly, see our guidelines doc/guidelines/frontend-api-calls.md
  • Always validate form, use zod for more complicated validations
  • Wrap APIs using create*API in api folder
  • Be careful in writing hooks, especially when using useEffect
  • Error Handling https://tkdodo.eu/blog/breaking-react-querys-api-on-purpose#a-bad-api
  • Lists are called *List and items of such a list are called *ListItem, e.g., LayerList and LayerListItem for a list of layers
  • Always label fields/attributes with their units like "Width (cm)" or "Scaling (pixels/meter)"
  • When checking for empty values in DTOs or validating form values, consider both null and undefined as empty value.
    Find more details in Validation section of Solution Strategy.

Utility Function Conventions

  • Use utility functions whenever code would be duplicated otherwise.
  • Add new utility functions to the appropriate utility file.
    • i.e. getPlantWidth is added to plant-utils.ts in the plant layer utils folder.
  • Add new utility files to the appropriate utils folder.
    • The global utils folder should contain files like date-utils.ts or string-utils.ts.
    • The map planning utils folder should contain files like layer-utils.ts or ShapesSelection.ts.
    • The plant layer utils folder contain files like plant-utils.ts or planting-utils.ts.
  • The utils folders should only contain TypeScript code.

Route Naming Conventions

  • Follow RESTful conventions for route names.
  • Use descriptive, plural nouns for resource collections.
  • Use placeholders for dynamic segments in route names.

Examples

  • View: /resource
  • Edit: /resource/:id/edit
  • Create: /resource/create

Incorporate Accessibility Best Practices

Writing code that is highly accessible and easily testable should be a priority whenever possible. While it may not always be the primary focus, if you can achieve both goals simultaneously, it's worth pursuing that path. Additionally, many accessibility best practices are inherent in standard coding practices, such as using appropriate HTML elements like h1s, button tags, providing alt attributes for images and using appropriate ARIA roles and attributes.

Documentation Best Practices

  • Any deviation from the default scroll direction (vertical) should be documented as part of the component documentation.