docs/conventions/frontend-coding.md

Frontend coding conventions

First principles and conventions for studyflash frontend code (portal, mobile-app, landing-page).

draftrajivconventionsfrontend

Status: draft scaffold. Replace TODOs with real content. PH comparison links are signposts, not prescriptions — we adopt selectively.

PH analogue: posthog.com/handbook/engineering/conventions/frontend-coding.

What already exists in this repo:

  • docs/agents/portal-code-style.md — portal-specific style notes (LLM-facing)
  • apps/portal/AGENTS.md, apps/portal/README.md
  • apps/mobile-app/AGENTS.md, apps/mobile-app/CLAUDE.md
  • apps/landing-page/AGENTS.md, apps/landing-page/CLAUDE.md

This doc supersedes / consolidates those once filled in.

First principles

TODO. Things to articulate:

  • What we optimize for (DX, perceived perf, accessibility).
  • Component composition vs inheritance default.
  • When to reach for a library vs build in-house.
  • Cross-app consistency (portal vs mobile-app vs landing-page).

Portal (Nuxt)

TODO.

  • Composables vs utils.
  • Data fetching (useAsyncData, Tanstack DB).
  • Routing / layouts.
  • i18n.

Mobile (Expo / React Native)

TODO.

  • React Compiler (no useCallback/useMemo).
  • Navigation patterns.
  • Data sync (tanstack-db + Powersync).
  • Platform divergence rules (iOS vs Android).

Landing page (Nuxt)

TODO.

  • Marketing site vs product app distinction.
  • Performance budget.

Open questions

TODO.