04-code-implementation-guidelines

Development Guidelines

General

• Write correct, DRY, bug-free code — leave no TODOs.
• Prefer functional components and hooks; use TypeScript types/interfaces consistently.
• Use early returns to reduce nesting.
• Choose descriptive names for variables, functions, and components.

Typing

• Use strict TypeScript: avoid any, unknown, and implicit any.
• Prefer interface over type aliases, unless a type cannot be expressed with an interface.
• Always type:
  • Props
  • State
  • Event handlers
  • Returned values
• Favor readonly and as const assertions for immutability and safety.
• Narrow types when possible (e.g., 'small' | 'medium' | 'large' instead of string).
• Use utility types like Partial, Pick, Omit thoughtfully to improve clarity and type safety.

Styling

• Use Tailwind CSS exclusively — do not use external CSS or styled-components.
• Use the cn utility from @/utils/utils for conditional class names.
  • Avoid ternaries in className strings.

Naming Conventions

• kebab-case for file names (e.g., my-component.tsx).
• camelCase for hooks and utility functions (e.g., useMyHook, formatDate).
• Prefix event handlers with handle (e.g., handleSubmit, handleClick).

Testing & QA

• Write tests using Vitest.
• Cover critical paths, edge cases, and user-facing logic.
• Provide fallback UI and error boundaries where appropriate.

REST API Best Practices

Shared Types

• Define shared types in: packages/types/src/index.ts
• Use them:
  • To serialize data in API routes (backend).
  • To deserialize and validate data on the frontend.
• This ensures type safety and consistency across backend and frontend.

Statelessness

• REST APIs must be stateless:
  • Each request must be self-contained.
  • The server must not depend on in-memory or session state.
• Clients manage session (e.g., cookies, auth headers, tokens).
• Use headers or tokens to communicate user context, not prior API calls.