WearPartTracker/.github/copilot-instructions.md

Copilot / AI Agent Instructions for this repository

Purpose: quick, practical guidance so an AI coding agent can be productive immediately.

• Big picture: This is a single-page Next.js (App Router) app that tracks bicycle wear parts. The UI lives under app/ (React Server/Client components) and server logic is implemented as Next API Route handlers under app/api/* (files named route.ts). Database access is via Prisma + SQLite; the Prisma client is in lib/prisma.ts and schema in prisma/schema.prisma.

• Key directories / files:

  • app/ — Next App Router. Routes and React components live here.
    • app/api/ — Route handlers (e.g. app/api/bikes/route.ts, app/api/bikes/[id]/route.ts). These are the server-side endpoints used by the frontend.
    • app/components/ — small client components. Note many components include 'use client' at the top (e.g. BikeDetail.tsx).
  • lib/prisma.ts — exports Prisma client; import this in route handlers.
  • lib/validations.ts — Zod schemas used both server-side and in tests.
  • prisma/schema.prisma — database schema (SQLite). Use Prisma commands after edits.
  • types/ — TypeScript types used across UI and APIs (e.g. BikeWithParts).
  • __tests__/ — Vitest tests; split into api/ and lib/ tests.

• Runtime & stack:

  • Uses Bun as the development runtime (bun run dev in README) but apps run as Next.js (v14). Keep using bun commands as the project expects.
  • Tailwind CSS for styling, Zod for validation, Prisma for DB.

• Project-specific conventions and patterns:

  • Next App Router pattern: server code under app/api/* uses route.ts exports. Edit these when changing backend behavior.
  • Client components explicitly use 'use client'. If a component needs browser APIs or state/hooks, it must be a client component.
  • The repo uses an import alias @ mapped to the project root (see vitest.config.ts). Tests and code reference @/ paths — preserve that style.
  • Database changes: update prisma/schema.prisma, then run Prisma generate/push. The README suggests bunx prisma generate and bunx prisma db push.

• Developer workflows (commands) — copyable examples:

  • Install deps: bun install
  • Dev server: bun run dev (runs next dev)
  • Build: bun run build
  • Prisma: bunx prisma generate then bunx prisma db push (or bun run db:push from package.json)
  • Open DB UI: bun run db:studio

• Testing:

  • Tests run with Vitest. Root scripts in package.json:
    • bun run test — runs vitest run --exclude '**/validations.test.ts' && bun test __tests__/lib/validations.test.ts (note: validations tests are run separately in this project).
    • bun run test:all — runs vitest run.
    • bun run test:ui — runs vitest --ui.
  • vitest.config.ts sets environment: 'node', globals: true, and the alias @ to the project root — tests assume these settings.
  • To run a single test file use: vitest run __tests__/api/bikes.test.ts or run the npm script with bun run.

• Editing APIs & DB changes:

  • When changing a route under app/api/*, update or add corresponding tests in __tests__/api/*.
  • When changing prisma/schema.prisma, run bunx prisma generate and bunx prisma db push. Update any affected lib/prisma.ts usages if the client API changes.

• What to avoid / gotchas:

  • Do not assume a separate backend service — API routes are in-repo Next route handlers.
  • Pay attention to client vs server components ('use client'). Moving code between them requires changing data fetching approaches.
  • Tests rely on the @ alias — preserve import paths like @/lib/validations rather than relative deep paths when modifying code.

• Where to look for examples:

  • API patterns: app/api/bikes/route.ts and app/api/bikes/[id]/route.ts.
  • Prisma usage: lib/prisma.ts and prisma/schema.prisma.
  • Validations: lib/validations.ts and __tests__/lib/validations.test.ts.
  • Client component example: app/components/BikeDetail.tsx uses local state, child forms (WearPartForm) and lists (WearPartList).

• If something is unclear: ask the maintainer these quick questions before making changes:

  1. Do you want to keep using bun for tests and dev, or prefer npm/pnpm wrappers? (README uses bun.)

2. Are there deployment targets or environment variables not in the repo? (DB URL / secrets)

Be concise in edits: when changing API behavior, update app/api/* and the corresponding tests in __tests__/api/ in the same PR.