.cursorrules

# Code Style Guide

## Core Principles

- Write concise TypeScript code.
- Use functional programming patterns.
- Prefer clean, readable code over compact code, using empty lines to separate logical blocks and improve readability.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError). Doesn't mater if it's long. For example this is good: "useGroupMembersInfoForCurrentAccount".
- Prefer clean and easy to read code over compact code.
- Don't create function(s) inside other functions unless it's specified
- Add clear, concise comments to explain non-obvious logic or unconventional implementation decisions.
- When refactoring code, preserve existing comments unless explicitly instructed otherwise or the related code is removed. Comments often explain important context or implementation decisions that should be maintained.
- Comments should be above the code they are describing.
- Use the suffix 'ForCurrentAccount' when using useCurrentAccount inside components or hooks.
- Handle errors at the caller level. Unless if we really need to log something but make sure to throw back the error to the caller.
- Minimize using external hooks inside custom hooks to prevent unnecessary rerenders. Instead, use getter functions to access data, especially in mutations.
- Use Zod for external API response validation. Define zod schema and infer types from it.
- Keep files small and focused. Place hooks and components in separate files unless they are small wrapper components. This improves code organization and maintainability.
- Refactor a component using the composable pattern when you start seeing a lot of optional props.

## TypeScript

- Use types over interfaces, prefixed with 'I' (e.g., IMyItem).
- Never use 'any'.
- Avoid enums, use maps instead.
- Use functional components with TypeScript types.
- Prefer inferring types if possible over explicit typing.
- Prefer type assertions on return objects (`return {...} satisfies IType`) over function return type annotations (`function(): IType`) if we have to put a type because the inferring is not working well.

## Function Patterns

- Use function keyword for pure functions.
- Prefer object params: `function(args: { name: string })` over `function(name: string)`.
- Destructure parameters at the top level.
  - Makes it clearer which properties are being used and
  - improves code readability.
  -
  - @example
  - // ❌ Bad: Nested destructuring
  - function getMetadataOptions(args: IArgs) {
  - const { account } = args;
  - }
  -
  - // ✅ Good: Top-level destructuring
  - function getMetadataOptions({ account, topic }: IArgs) {

## React & Components

- Use named exports.
- Write JSX inline rather than separate render functions.
- Prefer early returns over ternaries.
- Use array syntax for merged styles: `style={[{ color: "red" }, style]}`.
- Minimize useEffect and setState usage.
- Wrap components in memo() for performance.
- When creating a new component or custom hook, aim to minimize the number of props you pass. Instead, try to reuse existing hooks whenever possible. This is especially important if the props or arguments you want to pass are only needed within the new component or hook we wanted to pass are ONLY used in the new component or hook.
- When asked to extract a component or some code for custom hooks, create those in the same file.
- Keep related code close together by placing the exported component at the top of the file with related components directly underneath it.
- Avoid default exports to maintain consistent imports and easier refactoring.
  - Named exports make codebase more maintainable and
  - refactoring safer.
  -
  - @example
  - // ❌ Bad: Default export
  - export default function ProfileScreen()
  -
  - // ✅ Good: Named export
  - export function ProfileScreen()

## File Structure

- Use lower-kebab-case for directories and files (e.g., components/auth-wizard).
- Import paths from our project should start with @/.
- Use the same name for the file and the component.
- Keep features self-contained. Create a new feature folder if accessing features across boundaries.
- Place queries within their respective feature folders, but maintain queryKeys at the root level for better visibility.

## Theming & Styling

- Always use the theme for styling. Import it from @/theme/useAppTheme like `const { theme } = useAppTheme();`.
- Use components from @/design-system.
- Use the theme for colors and spacing.

## React Query Principles

- Avoid destructuring rest operators with useQuery.

  - Be explicit about which properties you need from useQuery
  - to prevent excessive re-rendering and performance issues.
  -
  - @example
  - // ❌ Bad: Causes unnecessary re-renders
  - const { data: conversations, ...rest } = useQuery()
  -
  - // ✅ Good: Explicit property usage
  - const { data: conversations, isLoading, error } = useQuery()

- Use object parameters for query options.
  - Pass query options as objects for better maintainability
  - and clearer intention.
  -
  - @example
  - // ❌ Bad: Positional arguments
  - useQuery(getConversationMessagesQueryOptions(account, topic))
  -
  - // ✅ Good: Object parameters
  - useQuery(getConversationMessagesQueryOptions({ account, topic }))