Torben Sorensen
d356d9dfb6
Some checks failed
Deploy to Test Environment / deploy-to-test (push) Failing after 43s
75 lines
3.8 KiB
Markdown
75 lines
3.8 KiB
Markdown
# ADR-005: Frontend State Management and Server Cache Strategy
|
|
|
|
**Date**: 2025-12-12
|
|
**Implementation Date**: 2026-01-08
|
|
|
|
**Status**: Accepted and Implemented (Phases 1 & 2 complete)
|
|
|
|
## Context
|
|
|
|
The frontend currently uses React's built-in hooks (`useState`, `useEffect`, `useContext`) for state management, as seen in `useAuth.tsx`. While effective for simple cases, this manual approach becomes complex and error-prone when fetching, caching, and synchronizing data with the server. It often leads to custom logic for loading states, errors, re-fetching, and optimistic updates.
|
|
|
|
## Decision
|
|
|
|
We will adopt a dedicated library for managing server state, such as **TanStack Query (formerly React Query)** or **SWR**, for all server-side data fetching on the client. This will abstract away the complexities of caching, background re-validation, and request deduplication.
|
|
|
|
## Consequences
|
|
|
|
**Positive**: Leads to a more performant, predictable, and simpler frontend codebase. Standardizes how the client-side communicates with the server and handles loading/error states. Improves user experience through intelligent caching.
|
|
**Negative**: Introduces a new frontend dependency. Requires a learning curve for developers unfamiliar with the library. Requires refactoring of existing data-fetching logic.
|
|
|
|
## Implementation Status
|
|
|
|
### Phase 1: Infrastructure & Core Queries (✅ Complete - 2026-01-08)
|
|
|
|
**Files Created:**
|
|
- [src/config/queryClient.ts](../../src/config/queryClient.ts) - Global QueryClient configuration
|
|
- [src/hooks/queries/useFlyersQuery.ts](../../src/hooks/queries/useFlyersQuery.ts) - Flyers data query
|
|
- [src/hooks/queries/useWatchedItemsQuery.ts](../../src/hooks/queries/useWatchedItemsQuery.ts) - Watched items query
|
|
- [src/hooks/queries/useShoppingListsQuery.ts](../../src/hooks/queries/useShoppingListsQuery.ts) - Shopping lists query
|
|
|
|
**Files Modified:**
|
|
- [src/providers/AppProviders.tsx](../../src/providers/AppProviders.tsx) - Added QueryClientProvider wrapper
|
|
- [src/providers/FlyersProvider.tsx](../../src/providers/FlyersProvider.tsx) - Refactored to use TanStack Query
|
|
- [src/providers/UserDataProvider.tsx](../../src/providers/UserDataProvider.tsx) - Refactored to use TanStack Query
|
|
- [src/services/apiClient.ts](../../src/services/apiClient.ts) - Added pagination params to fetchFlyers
|
|
|
|
**Benefits Achieved:**
|
|
- ✅ Removed ~150 lines of custom state management code
|
|
- ✅ Automatic caching of server data
|
|
- ✅ Background refetching for stale data
|
|
- ✅ React Query Devtools available in development
|
|
- ✅ Automatic data invalidation on user logout
|
|
- ✅ Better error handling and loading states
|
|
|
|
### Phase 2: Remaining Queries (✅ Complete - 2026-01-08)
|
|
|
|
**Files Created:**
|
|
- [src/hooks/queries/useMasterItemsQuery.ts](../../src/hooks/queries/useMasterItemsQuery.ts) - Master grocery items query
|
|
- [src/hooks/queries/useFlyerItemsQuery.ts](../../src/hooks/queries/useFlyerItemsQuery.ts) - Flyer items query
|
|
|
|
**Files Modified:**
|
|
- [src/providers/MasterItemsProvider.tsx](../../src/providers/MasterItemsProvider.tsx) - Refactored to use TanStack Query
|
|
- [src/hooks/useFlyerItems.ts](../../src/hooks/useFlyerItems.ts) - Refactored to use TanStack Query
|
|
|
|
**Benefits Achieved:**
|
|
- ✅ Removed additional ~50 lines of custom state management code
|
|
- ✅ Per-flyer item caching (items cached separately for each flyer)
|
|
- ✅ Longer cache times for infrequently changing data (master items)
|
|
- ✅ Automatic query disabling when dependencies are not met
|
|
|
|
### Phase 3: Mutations (⏳ Pending)
|
|
- Add/remove watched items
|
|
- Shopping list CRUD operations
|
|
- Optimistic updates
|
|
- Cache invalidation strategies
|
|
|
|
### Phase 4: Cleanup (⏳ Pending)
|
|
- Remove deprecated custom hooks
|
|
- Remove stub implementations
|
|
- Update all dependent components
|
|
|
|
## Implementation Guide
|
|
|
|
See [plans/adr-0005-implementation-plan.md](../../plans/adr-0005-implementation-plan.md) for detailed implementation steps.
|