Repository Guidelines#

Project Structure & Modules#

• apps/web: Vite + React 19 frontend (sources under src/, static assets in public/).
• apps/api: Hono-based API server (entry src/index.ts, routes in src/routes/).
• packages/*: Shared code (helpers, data, types, indexer, config).
• script/*: Maintenance utilities (e.g., sorting package.json, cleaning branches).
• Tooling: PNPM workspaces (pnpm-workspace.yaml), Biome config (biome.json), Husky hooks (.husky/).

Build, Test, and Development#

• Root dev: pnpm dev — run all workspaces in watch mode.
• Root build: pnpm build — build all workspaces in parallel.
• Web app: pnpm -F @hey/web dev (preview: pnpm -F @hey/web start, build: pnpm -F @hey/web build).
• API: pnpm -F @hey/api dev (typecheck: pnpm -F @hey/api typecheck).
• Lint/format: pnpm biome:check (auto-fix: pnpm biome:fix).
• Types: pnpm typecheck — TypeScript across the monorepo.
• Node & PM: Node 20 (.nvmrc), PNPM 10 (see package.json#packageManager).

Coding Style & Naming#

• Language: TypeScript (strict, shared configs in packages/config).
• Formatting: Biome controls style; no trailing commas; spaces for indentation.
• Imports: Use workspace packages (@hey/*) and web alias @/* to apps/web/src.
• Files: React components PascalCase.tsx; helpers/stores camelCase.ts.
• Keep modules small, colocate domain helpers with their feature when practical.

Testing Guidelines#

• Current status: no formal unit tests present. Enforce quality via biome and tsc.
• If adding tests, prefer Vitest for web and lightweight integration tests for API.
• Naming: *.test.ts or *.test.tsx, colocated with the code or under __tests__/.
• Run with a future pnpm test script at root or per package.

Commit & Pull Requests#

• Commits: imperative mood, concise subject; optional scope like web:, api:, helpers:.
• Include rationale and references (e.g., Closes #123).
• PRs: clear description, screenshots for UI changes, reproduction steps for fixes, and env notes.
• CI hooks: pre-commit runs biome and type checks; ensure both pass locally before pushing.

Security & Configuration#

• Copy .env.example to .env in apps/web and apps/api. Never commit secrets.
• Validate envs at startup; keep keys minimal and documented near usage.