Best Practices

These guidelines keep the codebase consistent and maintainable as the team and project grow.

Code quality

  • Write TypeScript with strict mode enabled. Avoid any unless you have a documented reason.
  • Use named exports for components and functions. Default exports are reserved for pages.
  • Keep files under 300 lines. If a file grows larger, split it into focused modules.
  • Co-locate related code: place a component's types, helpers, and tests near the component file.

Naming conventions

ItemConventionExample
ComponentsPascalCaseTaskCard.tsx
UtilitiescamelCaseformatDate.ts
Convex functionscamelCaselistByProject.ts
CSS variableskebab-case--color-primary
Environment varsUPPER_SNAKECONVEX_URL
Directorieskebab-caseschema-design/

Pull request workflow

  1. Create a branch from main using the pattern <type>/<short-description> (e.g., feat/task-list).
  2. Keep PRs small — aim for fewer than 400 changed lines.
  3. Write a summary in the PR body that explains why, not just what.
  4. Request at least one reviewer. Address feedback with new commits, not force-pushes.
  5. Squash-merge into main once approved.

Commit messages

  • Use present tense: "Add task list" not "Added task list".
  • Start with a verb: Add, Fix, Update, Remove, Refactor.
  • Keep the first line under 72 characters.
Add real-time task list with optimistic updates

Introduces a TaskList component that subscribes to tasks via useQuery
and applies optimistic updates on create and delete.

Testing standards

  • Write unit tests for utility functions and Convex query/mutation logic.
  • Use React Testing Library for component tests; avoid testing implementation details.
  • Name test files with .test.ts or .test.tsx suffixes alongside the source file.

Documentation requirements

  • Every new page or feature should have a corresponding MDX doc in app/docs/.
  • Update the sidebar navigation when adding new doc pages.
  • Include at least one code example per doc page.

Accessibility

  • All interactive elements must be keyboard accessible.
  • Use semantic HTML (<nav>, <main>, <section>) over generic <div> wrappers.
  • shadcn/ui components are built on Radix, which provides ARIA roles by default — do not strip them.