mutation-query.md

Creating New Mutations and Queries

Follow these steps in order, using existing files as references:

1. Update Schema

   • Edit packages/db/prisma/schema.prisma
   • Run prisma generate and prisma db push
   • Reference: Existing models in schema.prisma

2. Create or Update Router

   • Location: packages/trpc/src/routers/<feature>/<feature>.router.ts
   • Use protectedProcedure for authenticated routes
   • Import prisma from @app/db/server
   • Reference: packages/trpc/src/routers/document/document.router.ts

3. Update App Router (if new router created)

   • File: packages/trpc/src/routers/app.router.ts
   • Reference: Existing router imports and additions

4. Create Mutation Hook

   • Location: apps/web/src/hooks/mutations/use<Action><Feature>Mutation.ts
   • Use useApi().<feature>.utils() for optimistic updates
   • Reference: apps/web/src/hooks/mutations/useCreateDocumentMutation.ts

5. Create Query (if needed)

   • Add to the feature router created in step 2
   • Reference: Existing queries in document.router.ts

6. Create Query File

   • For single item: apps/web/src/lib/react-query/queries/query-<feature>.tsx
   • For list: apps/web/src/lib/react-query/queries/query-<feature>s.tsx
   • Reference: apps/web/src/lib/react-query/queries/query-document.tsx or query-documents.tsx

7. Update API Hook

   • File: apps/web/src/lib/react-query/useApi.ts
   • Add only queries, not mutations
   • Reference: Existing structure in useApi.ts

8. Update Mutation Hook (if needed)

   • Use the query in the mutation hook if required
   • Reference: useCreateDocumentMutation.ts or similar existing hooks

9. Implement in Components

   • Use the mutation/query in relevant components
   • Reference: apps/web/src/components/references/trash-box.tsx or similar components

Remember:

• Follow existing naming conventions and file structures
• Use useAuthGuard for protected actions in components
• Keep code consistent with the project's patterns
• Always refer to existing files for patterns and conventions