Skip to main content

Code Style

General Rules​

  • TypeScript strict mode, no any
  • ES modules only (import/export), never CommonJS
  • 2-space indentation, single quotes
  • Prefer named exports over default exports
  • Small domain public API barrels are allowed at src/modules/<domain>/index.ts. Do not add broad recursive barrels, wildcard re-exports, a root src/modules/index.ts, or barrels with side effects.
  • Use @/ path alias for imports from src/

Formatting and Linting​

bun lint      # biome + oxlint
bun format    # biome
bun tsc --noEmit  # type check

WEFA Naming Conventions​

  • Providers: WEFA* (e.g., WEFAAuthProvider, WEFAProvider)
  • Storage keys: wefa_* (e.g., wefa_auth_mode)
  • Database names: wefa-* (e.g., wefa-db)

File Organization​

  • Shared interfaces and types live in src/types/; route-local or domain-local API types can live beside the route/module they validate.
  • Shared Zod schemas in src/types/ export both the schema and inferred type; API route-local schemas stay in the API route package.
  • State machines in src/machines/
  • Domain logic in src/modules/
  • React hooks in src/hooks/, organized by domain
  • View components in src/views/
  • Reusable components in src/components/
  • View-level state stores in src/stores/ (Zustand)

Common Gotchas​

  • Dexie live queries need useLiveQuery, not TanStack Query for reactive local data
  • bitECS components use typed arrays (numbers only, no strings or objects)
  • Yjs Y.Map observations fire on every remote change — debounce UI updates
  • Meshy Image-to-3D takes 60-120s — always use story interstitial during wait
  • iOS Safari IndexedDB has ~50MB quota — monitor with cache management
  • XState 5 uses setup() API, not createMachine() from v4
  • R3F <Canvas> must not be nested inside another <Canvas>