2.7 KiB
Repository Guidelines
Project Structure & Module Organization
Source boots from index.tsx into App.tsx. Feature UIs live in components/, shared context in contexts/, and reusable hooks under hooks/. Network clients stay in services/; supporting utilities and shared types sit in utils/ and types/. Configuration belongs in config/, while CouchDB credentials and seeds are organized in couchdb-config/ and couchdb-data/. Tests live alongside code with broader integration suites in tests/; docs and proposals belong in docs/.
Build, Test, and Development Commands
Run bun run dev (or make dev) for the Vite development server. bun run build compiles a production bundle; verify it locally with bun run preview. Guard quality with bun run lint, bun run format:check, and bun run type-check. Execute the full Jest suite via bun run test, switching to bun run test:watch or bun run test:coverage when iterating. Make targets (make build, make test) wrap the same tasks for CI parity.
Coding Style & Naming Conventions
All code is TypeScript; use .tsx for React components and .ts elsewhere. Prettier enforces 2-space indentation, trailing commas, and quote consistency—run bun run format:check before committing. Follow ESLint rules (hooks lifecycle, no-unused-vars, no console outside tests). Name components in PascalCase, hooks as useThing, and tests as Feature.test.ts[x]. Keep configuration constants in SCREAMING_SNAKE_CASE and load env-specific values through config/ helpers.
Testing Guidelines
Jest with React Testing Library drives component coverage. Prefer colocated tests to mirror features; integration flows live under tests/integration/. Mock CouchDB requests with the lightweight service helpers instead of hitting live endpoints. Aim for meaningful assertions over snapshots unless the UI is intentionally static. Keep coverage balanced across hooks and service contracts before merging.
Commit & Pull Request Guidelines
Commits follow Conventional Commits (type(scope): imperative summary) and should contain a single logical change. Ensure lint, format, and tests pass locally; Husky will re-run the checks. Pull requests should describe motivation, summarize implementation decisions, and list manual test evidence. Link relevant tickets or CouchDB tasks, include screenshots or terminal output for UI/CLI changes, and flag migrations so reviewers can reproduce.
Security & Configuration Tips
Never commit real secrets—copy .env.example when you need local overrides. Use bun run check:secrets before pushing whenever credentials might be touched. Prefer config/ accessors over hard-coded URLs or keys, and store CouchDB credentials in the secure store rather than the repo.