scaffold-frontend-feature

Follow this guide to implement a responsive frontend feature in src/Web/BookStore.Web.

1. Prerequisites

   • Ensure the API Client exists: src/Client/BookStore.Client/I{Resource}Client.cs.
   • Ensure the Shared/Response DTOs exist in BookStore.Shared.
   • if NOT, run /scaffold-read or /scaffold-write first.

2. Create the Component

   • Create/Update src/Web/BookStore.Web/Components/Pages/{Feature}.razor.
   • Template: templates/Page.razor
   • Lifecycle: Use OnInitializedAsync to start listening: EventsService.StartListening();.

3. Implement Data Fetching

   • Pattern: Use ReactiveQuery<T>.
   • Setup (Template): templates/ReactiveQueryInit.cs

4. Implement Optimistic Updates (Properties)

   • Use Case: Toggling a boolean, changing a number (e.g., Favorites).
   • Pattern: Mutate -> Call -> Rollback.

     query.MutateData(s => s with { IsFavorite = true }); // 1. Instant UI update
     try {
         await Client.UpdateAsync(); // 2. API Call
     } catch {
         query.MutateData(s => s with { IsFavorite = false }); // 3. Revert on error
     }
     

5. Implement Optimistic Updates (Lists)

   • Use Case: Adding a new item to a list instantly.
   • Pattern:

     OptimisticService.AddOptimisticBook(id, title); // 1. Add to separate list
     await Client.CreateAsync(); // 2. API Call (Event will confirm/remove it)
     

   • UI: Merge query.Data with OptimisticService.GetOptimisticBooks() when rendering lists.

6. Configure Invalidation

   • Open src/Web/BookStore.Web/Services/QueryInvalidationService.cs.
   • Add cases to GetInvalidationKeys(IDomainEventNotification notification).
   • Rule: Map the Domain Event (e.g., BookCreated) to the Query Keys you defined in Step 2 (e.g., "Books").

7. Verify

   • Run the app and verify:
     1. Data loads.
     2. Mutations update UI instantly.
     3. SSE events (from other tabs/users) trigger auto-refetch.
   • Run /verify-feature for complete verification.

Related Skills

Prerequisites:

• Backend endpoints must exist first:
  • /scaffold-write - For mutation endpoints
  • /scaffold-read - For query endpoints
• Client SDK must be configured (usually done by scaffold-write/read)

Next Steps:

• /scaffold-test - Create integration tests for the feature
• /verify-feature - Complete verification

Debugging:

• /debug-sse - If real-time updates don't work
• /debug-cache - If query data is stale

See Also:

• real-time-notifications - SSE architecture
• scaffold-write - Backend mutations
• scaffold-read - Backend queries
• Web AGENTS.md - ReactiveQuery patterns and SSE integration