Skip to content

AGENTS.md

Latest commit

 

History

History
36 lines (22 loc) · 2.92 KB

AGENTS.md

File metadata and controls

36 lines (22 loc) · 2.92 KB
Raw

Repository Guidelines

Project Structure & Module Organisation

app/ holds the Next.js App Router: UI routes live in app/(routes)/, and server handlers live in app/api/. Put feature UI in components/features/, reusable primitives in components/ui/, and shared state in contexts/. API/data logic belongs in lib/services/, config in lib/config/, and utilities in lib/utils/. The Cloudflare Supabase worker lives in workers/ with config in wrangler.supabase.toml. Tests are colocated as *.test.ts or *.test.tsx. Assets live in public/, shared data in constants/, and types in types/.

Build, Test, and Development Commands

Use pnpm.

  • pnpm install: install dependencies.
  • pnpm dev: start the Next.js app on http://localhost:3000.
  • pnpm build: create a production build.
  • pnpm start: serve the production build locally.
  • pnpm lint: run ESLint with the Next.js ruleset.
  • pnpm test: run the Jest suite.
  • pnpm test:coverage: run Jest with coverage collection and enforce the 95% threshold.
  • npx wrangler dev --config wrangler.supabase.toml: run the Supabase worker.

Coding Style & Naming Conventions

TypeScript is strict, so prefer explicit types for props, service inputs, and return values. Follow the existing React style: functional components, hooks prefixed with use, PascalCase components, and camelCase helpers/services. Use the @/ aliases from tsconfig.json for cross-folder imports. Match the surrounding file’s formatting; the codebase mostly uses compact files and 2-space indentation. Linting comes from next/core-web-vitals and next/typescript. Use Australian English spellings throughout all code, comments, and documentation.

Testing Guidelines

Jest and React Testing Library are the default tools. Keep tests beside the code they cover and name them Component.test.tsx, service.test.ts, or similar. Mock network calls in service tests and assert rendered behaviour in route and component tests. Test coverage is enforced.

After any substantive code change, run pnpm validate:push (type-check + lint + coverage) to confirm nothing is broken before considering the task done.

Commit & Pull Request Guidelines

Recent history favours short, imperative commit subjects such as improve prompt, with optional prefixes like refactor: for scoped cleanup. Keep each commit focused on one logical change. Pull requests should summarise behaviour changes, note env or worker config updates, link the relevant issue when available, and include screenshots for UI changes. Before opening a PR, run pnpm lint and pnpm test:coverage and mention anything you could not verify.

Environment & Configuration Tips

Store app variables in .env.local and worker secrets in .dev.vars; never commit either file. SUPABASE_WORKER_URL defaults to http://localhost:7878, so keep local Wrangler ports aligned, and keep SUPABASE_WORKER_SECRET in sync with WORKER_SHARED_SECRET.