Frontend Architecture
Part 9 of 110. Frontend Observability: Logs, Traces and Metrics Are Not Just a Backend Concern0. The Hidden Cost of "Just Add a Library"0. JavaScript Build Tooling Is a Product Decision1. Designing a Component Library That Teams Actually Adopt1. State Management at Scale — Beyond Redux, a Pragmatic Guide2. Micro-Frontend Architecture: Worth the Complexity or Not?3. Rendering Strategies in Next.js: SSR, SSG, ISR, PPR — When to Use What5. API Design Principles That Stand the Test of Time (REST vs GraphQL vs tRPC)7. CSS Architecture at Scale: The Decision Nobody Takes Seriously Until It Hurts8. The Strangler Fig Pattern: Migrating Legacy Systems Without a Rewrite9. Data Fetching Architecture in React Apps
Data Fetching Architecture in React Apps
February 21, 20263 min read8 views
Data Fetching Architecture in React Apps
React Query vs SWR vs server components vs Apollo — not a feature comparison but an architectural fit guide based on app complexity, team size, and data patterns
Beyond the Feature Matrix
Every "React Query vs SWR vs Apollo" article compares features. Cache invalidation options, bundle sizes, TypeScript support. But when you're architecting a real application, features don't matter—fit matters.
The question isn't "which library has more features?" It's "which approach matches my data patterns, team capabilities, and application complexity?" A feature-rich solution that doesn't fit your architecture will create more problems than it solves.
This guide will help you choose based on what actually matters: how your data flows, how your team works, and where your application is headed.
Understanding Data Fetching Patterns
Before choosing tools, understand your data:
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA PATTERN DIMENSIONS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Dimension 1: Data Ownership │
│ ──────────────────────────── │
│ Server-Owned Shared Client-Owned │
│ ──────────────────────────────────────────────────────────────── │
│ Data lives on server Data synced Data lives in │
│ Client is a cache between both browser only │
│ Examples: Examples: Examples: │
│ • User profiles • Collaborative • Form drafts │
│ • Product catalog docs • UI preferences │
│ • Order history • Real-time chat • Undo history │
│ • Multiplayer │
│ │
│ Dimension 2: Update Frequency │
│ ───────────────────────────── │
│ Static Periodic Real-time │
│ ──────────────────────────────────────────────────────────────── │
│ Changes rarely Changes Changes │
│ Cache aggressively occasionally constantly │
│ Examples: Examples: Examples: │
│ • App config • User data • Live scores │
│ • Feature flags • Feed content • Stock prices │
│ • Static content • Notifications • Chat messages │
│ │
│ Dimension 3: Data Shape │
│ ─────────────────────── │
│ Document Normalized Graph │
│ ──────────────────────────────────────────────────────────────── │
│ Self-contained Entities with Complex │
│ objects relationships relationships │
│ Examples: Examples: Examples: │
│ • Blog posts • Users + Orders • Social network │
│ • Comments • Products + Tags • Knowledge base │
│ • Settings • Teams + Members • Recommendation │
│ │
│ Dimension 4: Consistency Requirements │
│ ───────────────────────────────────── │
│ Eventual Read-your-writes Strong │
│ ──────────────────────────────────────────────────────────────── │
│ Updates can lag User sees own All users see │
│ seconds/minutes changes immediately same data │
│ Examples: Examples: Examples: │
│ • Analytics • Profile updates • Banking │
│ • Recommendations • Post creation • Reservations │
│ • Social feeds • Settings changes • Inventory │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Data Pattern Assessment
// Use this to assess your application's data patterns
interface DataPatternAssessment {
// Primary data characteristics
ownership: 'server' | 'shared' | 'client';
updateFrequency: 'static' | 'periodic' | 'realtime';
shape: 'document' | 'normalized' | 'graph';
consistency: 'eventual' | 'read-your-writes' | 'strong';
// Complexity factors
numberOfEntities: number; // How many different data types
crossEntityRelationships: boolean; // Do entities reference each other
offlineRequirements: boolean; // Must work offline
optimisticUpdates: boolean; // Need instant UI feedback
// Scale factors
dataVolumePerPage: 'low' | 'medium' | 'high'; // KB of data per page
concurrentQueries: number; // Parallel requests typical
cacheComplexity: 'simple' | 'moderate' | 'complex';
// Team factors
teamSize: number;
graphQLExperience: boolean;
backendControl: boolean; // Can you change the API?
}
// Example assessments
const simpleApp: DataPatternAssessment = {
ownership: 'server',
updateFrequency: 'periodic',
shape: 'document',
consistency: 'read-your-writes',
numberOfEntities: 5,
crossEntityRelationships: false,
offlineRequirements: false,
optimisticUpdates: false,
dataVolumePerPage: 'low',
concurrentQueries: 2,
cacheComplexity: 'simple',
teamSize: 3,
graphQLExperience: false,
backendControl: true,
};
// Recommendation: SWR or simple React Query
const complexDashboard: DataPatternAssessment = {
ownership: 'server',
updateFrequency: 'periodic',
shape: 'normalized',
consistency: 'read-your-writes',
numberOfEntities: 25,
crossEntityRelationships: true,
offlineRequirements: false,
optimisticUpdates: true,
dataVolumePerPage: 'high',
concurrentQueries: 10,
cacheComplexity: 'complex',
teamSize: 8,
graphQLExperience: false,
backendControl: true,
};
// Recommendation: React Query with careful cache design
const socialPlatform: DataPatternAssessment = {
ownership: 'shared',
updateFrequency: 'realtime',
shape: 'graph',
consistency: 'read-your-writes',
numberOfEntities: 50,
crossEntityRelationships: true,
offlineRequirements: true,
optimisticUpdates: true,
dataVolumePerPage: 'high',
concurrentQueries: 15,
cacheComplexity: 'complex',
teamSize: 20,
graphQLExperience: true,
backendControl: true,
};
// Recommendation: Apollo Client or Relay
The Options Landscape
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA FETCHING OPTIONS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Simplicity ◄────────────────────────────► Power │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ fetch + │ │ SWR │ │ React Query │ │ Apollo │ │
│ │ useState │ │ │ │ │ │ Client │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ │ │ │ │ │ │
│ │ No learning │ Minimal │ Moderate │ Significant │ │
│ │ curve │ learning │ learning │ learning │ │
│ │ │ curve │ curve │ curve │ │
│ │ │ │ │ │ │
│ │ Manual │ Auto cache │ Powerful │ Normalized │ │
│ │ everything │ & revalidate │ cache mgmt │ cache │ │
│ │ │ │ │ │ │
│ │ No cache │ URL-based │ Query-key │ Entity-based │ │
│ │ │ cache │ cache │ cache │ │
│ │ │ │ │ │ │
│ │ REST only │ REST focused │ Any protocol │ GraphQL │ │
│ │ │ │ │ native │ │
│ │
│ ───────────────────────────────────────────────────────────────────── │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Server │ │ Relay │ │
│ │ Components │ │ │ │
│ └─────────────┘ └─────────────┘ │
│ │
│ │ │ │ │
│ │ Next.js/RSC │ Facebook's │ │
│ │ only │ GraphQL lib │ │
│ │ │ │ │
│ │ No client │ Compiler- │ │
│ │ state │ based │ │
│ │ │ │ │
│ │ Server │ Maximum │ │
│ │ rendering │ type safety │ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Server Components: The New Baseline
Before choosing a client-side solution, ask: do you even need one?
When Server Components Are Enough
// Server Components handle many data fetching patterns elegantly
// app/products/page.tsx
async function ProductsPage() {
// Direct database access - no API layer needed
const products = await prisma.product.findMany({
where: { active: true },
include: { category: true },
orderBy: { createdAt: 'desc' },
});
return (
<div className="grid grid-cols-3 gap-4">
{products.map(product => (
<ProductCard key={product.id} product={product} />
))}
</div>
);
}
// Parallel data fetching - automatic
async function DashboardPage() {
// These run in parallel automatically
const [stats, recentOrders, topProducts] = await Promise.all([
getStats(),
getRecentOrders(),
getTopProducts(),
]);
return (
<div>
<StatsOverview stats={stats} />
<RecentOrders orders={recentOrders} />
<TopProducts products={topProducts} />
</div>
);
}
// Nested data fetching with Suspense
async function UserProfile({ userId }: { userId: string }) {
const user = await getUser(userId);
return (
<div>
<UserHeader user={user} />
{/* This fetches in parallel, streams when ready */}
<Suspense fallback={<OrdersSkeleton />}>
<UserOrders userId={userId} />
</Suspense>
<Suspense fallback={<ReviewsSkeleton />}>
<UserReviews userId={userId} />
</Suspense>
</div>
);
}
Server Components Limitations
┌─────────────────────────────────────────────────────────────────────────────┐
│ SERVER COMPONENTS: WHEN THEY'RE NOT ENOUGH │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Need Client Data Fetching When: │
│ │
│ ❌ User interactions trigger data changes │
│ • Pagination, filtering, sorting by user │
│ • Search with debouncing │
│ • Infinite scroll │
│ │
│ ❌ Data needs to update without navigation │
│ • Polling for updates │
│ • Real-time subscriptions │
│ • Refetch after mutations │
│ │
│ ❌ Optimistic updates required │
│ • Like/unlike buttons │
│ • Add to cart │
│ • Any action where waiting feels slow │
│ │
│ ❌ Complex cache management │
│ • Same data used in multiple places │
│ • Partial updates to cached data │
│ • Background refetching │
│ │
│ ❌ Offline support │
│ • Data must persist across page loads │
│ • Mutations queue when offline │
│ │
│ Server Components + Client Fetching library is often the answer │
│ Initial data: Server Components │
│ Interactive updates: React Query/SWR │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Hybrid Pattern: Server Components + Client Fetching
// The best of both worlds
// app/products/page.tsx (Server Component)
import { HydrationBoundary, dehydrate } from '@tanstack/react-query';
import { getQueryClient } from '@/lib/query-client';
import { ProductList } from './product-list';
export default async function ProductsPage() {
const queryClient = getQueryClient();
// Prefetch on server
await queryClient.prefetchQuery({
queryKey: ['products', { page: 1 }],
queryFn: () => fetchProducts({ page: 1 }),
});
return (
// Pass server state to client
<HydrationBoundary state={dehydrate(queryClient)}>
<ProductList />
</HydrationBoundary>
);
}
// app/products/product-list.tsx (Client Component)
'use client';
import { useQuery } from '@tanstack/react-query';
import { useState } from 'react';
export function ProductList() {
const [page, setPage] = useState(1);
const [search, setSearch] = useState('');
// Hydrates from server, then handles client interactions
const { data, isLoading, isPlaceholderData } = useQuery({
queryKey: ['products', { page, search }],
queryFn: () => fetchProducts({ page, search }),
placeholderData: keepPreviousData,
});
return (
<div>
<SearchInput value={search} onChange={setSearch} />
<ProductGrid products={data?.products} loading={isLoading} />
<Pagination
page={page}
totalPages={data?.totalPages}
onChange={setPage}
disabled={isPlaceholderData}
/>
</div>
);
}
SWR: The Simple Choice
SWR is perfect when you want caching without complexity.
SWR Sweet Spot
┌─────────────────────────────────────────────────────────────────────────────┐
│ SWR IDEAL USE CASES │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Perfect For: │
│ ───────────── │
│ • Small to medium applications │
│ • Teams new to data fetching libraries │
│ • Simple cache requirements (URL-based) │
│ • Read-heavy applications (few mutations) │
│ • Vercel/Next.js ecosystem alignment │
│ │
│ Key Strengths: │
│ ─────────────── │
│ • Minimal API surface - learn in an hour │
│ • Stale-while-revalidate out of the box │
│ • Automatic revalidation on focus/reconnect │
│ • Small bundle (~4KB) │
│ • Simple mental model │
│ │
│ Limitations: │
│ ───────────── │
│ • Mutations are basic (no optimistic by default) │
│ • No normalized cache │
│ • Limited query invalidation patterns │
│ • DevTools not as powerful │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
SWR Patterns
// lib/swr/hooks.ts
import useSWR, { mutate } from 'swr';
import useSWRMutation from 'swr/mutation';
// Standard fetcher
const fetcher = (url: string) => fetch(url).then(r => r.json());
// Basic usage - dead simple
export function useUser(userId: string) {
return useSWR(`/api/users/${userId}`, fetcher);
}
// With options
export function useProducts(filters: ProductFilters) {
const params = new URLSearchParams(filters as Record<string, string>);
return useSWR(
`/api/products?${params}`,
fetcher,
{
revalidateOnFocus: false, // Don't refetch on tab focus
dedupingInterval: 60000, // Dedupe requests within 1 minute
keepPreviousData: true, // Keep showing old data while fetching
}
);
}
// Conditional fetching
export function useUserOrders(userId: string | null) {
// Pass null key to disable fetching
return useSWR(
userId ? `/api/users/${userId}/orders` : null,
fetcher
);
}
// Mutations with useSWRMutation
export function useCreateOrder() {
return useSWRMutation(
'/api/orders',
async (url: string, { arg }: { arg: CreateOrderInput }) => {
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(arg),
});
if (!response.ok) {
throw new Error('Failed to create order');
}
return response.json();
},
{
onSuccess: () => {
// Revalidate related data
mutate('/api/orders');
mutate(key => typeof key === 'string' && key.startsWith('/api/users/'));
},
}
);
}
// SWR's simplicity means manual optimistic updates
export function useLikePost() {
return useSWRMutation(
'/api/like',
async (url: string, { arg }: { arg: { postId: string } }) => {
const response = await fetch(url, {
method: 'POST',
body: JSON.stringify(arg),
});
return response.json();
},
{
// Optimistic update requires more manual work
onMutate: async ({ postId }) => {
// Update local cache optimistically
mutate(
`/api/posts/${postId}`,
(current: Post) => ({
...current,
likes: current.likes + 1,
likedByMe: true,
}),
{ revalidate: false }
);
},
onError: (error, { postId }) => {
// Rollback on error
mutate(`/api/posts/${postId}`);
},
}
);
}
When to Outgrow SWR
// Signs you might need more than SWR:
// 1. Complex cache invalidation patterns
// SWR: Manual, URL-based
mutate('/api/orders');
mutate(key => typeof key === 'string' && key.includes('/orders'));
// Can get messy with many related queries
// 2. Optimistic updates become boilerplate
// Every mutation needs manual optimistic/rollback logic
// React Query's mutation context handles this better
// 3. You need query cancellation
// SWR doesn't have built-in query cancellation
// Long-running queries can cause race conditions
// 4. Parallel dependent queries
// "Fetch user, then fetch their permissions, then fetch their team"
// useQueries in React Query handles this elegantly
// 5. Offline support
// SWR's offline story is limited
// React Query has built-in offline mutation persistence
React Query: The Pragmatic Powerhouse
React Query (TanStack Query) hits the sweet spot for most complex applications.
React Query Sweet Spot
┌─────────────────────────────────────────────────────────────────────────────┐
│ REACT QUERY IDEAL USE CASES │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Perfect For: │
│ ───────────── │
│ • Medium to large applications │
│ • Teams wanting structure without GraphQL │
│ • REST/RPC APIs (works with anything) │
│ • Applications with complex mutations │
│ • When you need fine-grained cache control │
│ │
│ Key Strengths: │
│ ─────────────── │
│ • Powerful cache invalidation (query keys) │
│ • Built-in optimistic updates │
│ • Excellent mutation handling │
│ • Great DevTools │
│ • TypeScript-first │
│ • Offline mutation persistence │
│ • Works with any async function │
│ │
│ Limitations: │
│ ───────────── │
│ • More concepts to learn │
│ • Cache is not normalized (by design) │
│ • Larger bundle (~13KB) │
│ • Can over-engineer simple apps │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
React Query Architecture Patterns
// lib/queries/query-keys.ts
// Structured query keys for consistent cache management
export const queryKeys = {
// User domain
users: {
all: ['users'] as const,
lists: () => [...queryKeys.users.all, 'list'] as const,
list: (filters: UserFilters) =>
[...queryKeys.users.lists(), filters] as const,
details: () => [...queryKeys.users.all, 'detail'] as const,
detail: (id: string) => [...queryKeys.users.details(), id] as const,
},
// Order domain
orders: {
all: ['orders'] as const,
lists: () => [...queryKeys.orders.all, 'list'] as const,
list: (filters: OrderFilters) =>
[...queryKeys.orders.lists(), filters] as const,
details: () => [...queryKeys.orders.all, 'detail'] as const,
detail: (id: string) => [...queryKeys.orders.details(), id] as const,
byUser: (userId: string) =>
[...queryKeys.orders.all, 'user', userId] as const,
},
// Product domain
products: {
all: ['products'] as const,
lists: () => [...queryKeys.products.all, 'list'] as const,
list: (filters: ProductFilters) =>
[...queryKeys.products.lists(), filters] as const,
detail: (id: string) => [...queryKeys.products.all, 'detail', id] as const,
inventory: (id: string) =>
[...queryKeys.products.all, 'inventory', id] as const,
},
};
// Usage: Surgical cache invalidation
queryClient.invalidateQueries({
queryKey: queryKeys.orders.byUser(userId)
});
// Invalidate all orders
queryClient.invalidateQueries({
queryKey: queryKeys.orders.all
});
// lib/queries/hooks/use-orders.ts
// Feature-complete query hook
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { queryKeys } from '../query-keys';
interface UseOrdersOptions {
userId?: string;
status?: OrderStatus;
page?: number;
enabled?: boolean;
}
export function useOrders(options: UseOrdersOptions = {}) {
const { userId, status, page = 1, enabled = true } = options;
return useQuery({
queryKey: queryKeys.orders.list({ userId, status, page }),
queryFn: () => fetchOrders({ userId, status, page }),
enabled,
staleTime: 5 * 60 * 1000, // Fresh for 5 minutes
gcTime: 30 * 60 * 1000, // Keep in cache for 30 minutes
placeholderData: keepPreviousData, // Keep showing while paginating
});
}
export function useOrder(orderId: string) {
return useQuery({
queryKey: queryKeys.orders.detail(orderId),
queryFn: () => fetchOrder(orderId),
staleTime: 60 * 1000,
});
}
export function useCreateOrder() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: createOrder,
// Optimistic update
onMutate: async (newOrder) => {
// Cancel outgoing refetches
await queryClient.cancelQueries({
queryKey: queryKeys.orders.lists()
});
// Snapshot previous value
const previousOrders = queryClient.getQueryData(
queryKeys.orders.list({})
);
// Optimistically update
queryClient.setQueryData(
queryKeys.orders.list({}),
(old: OrdersResponse) => ({
...old,
orders: [{ ...newOrder, id: 'temp', status: 'pending' }, ...old.orders],
})
);
return { previousOrders };
},
onError: (error, variables, context) => {
// Rollback on error
if (context?.previousOrders) {
queryClient.setQueryData(
queryKeys.orders.list({}),
context.previousOrders
);
}
},
onSettled: () => {
// Refetch to ensure consistency
queryClient.invalidateQueries({
queryKey: queryKeys.orders.lists()
});
},
});
}
export function useUpdateOrderStatus() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: ({ orderId, status }: { orderId: string; status: OrderStatus }) =>
updateOrderStatus(orderId, status),
onMutate: async ({ orderId, status }) => {
await queryClient.cancelQueries({
queryKey: queryKeys.orders.detail(orderId)
});
const previousOrder = queryClient.getQueryData<Order>(
queryKeys.orders.detail(orderId)
);
// Update the specific order
queryClient.setQueryData(
queryKeys.orders.detail(orderId),
(old: Order) => ({ ...old, status })
);
// Also update in lists
queryClient.setQueriesData(
{ queryKey: queryKeys.orders.lists() },
(old: OrdersResponse | undefined) => {
if (!old) return old;
return {
...old,
orders: old.orders.map(order =>
order.id === orderId ? { ...order, status } : order
),
};
}
);
return { previousOrder };
},
onError: (error, { orderId }, context) => {
if (context?.previousOrder) {
queryClient.setQueryData(
queryKeys.orders.detail(orderId),
context.previousOrder
);
}
queryClient.invalidateQueries({
queryKey: queryKeys.orders.lists()
});
},
});
}
React Query + Server Components
// lib/query-client.ts
import { QueryClient } from '@tanstack/react-query';
import { cache } from 'react';
// Server-side query client (one per request)
export const getQueryClient = cache(() => new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000,
},
},
}));
// app/providers.tsx
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { useState } from 'react';
export function Providers({ children }: { children: React.ReactNode }) {
// Client-side query client (one per app lifecycle)
const [queryClient] = useState(() => new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000,
refetchOnWindowFocus: false,
},
},
}));
return (
<QueryClientProvider client={queryClient}>
{children}
<ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>
);
}
Apollo Client: The GraphQL Native
Apollo makes sense when GraphQL is your foundation, not an afterthought.
Apollo Sweet Spot
┌─────────────────────────────────────────────────────────────────────────────┐
│ APOLLO CLIENT IDEAL USE CASES │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Perfect For: │
│ ───────────── │
│ • GraphQL-first architectures │
│ • Complex data relationships (graph-shaped data) │
│ • Large teams where schema is the contract │
│ • Applications needing normalized cache │
│ • Real-time subscriptions as core feature │
│ │
│ Key Strengths: │
│ ─────────────── │
│ • Normalized cache - update once, reflects everywhere │
│ • GraphQL-native (queries, mutations, subscriptions) │
│ • Type generation from schema │
│ • Mature ecosystem │
│ • Local state management built-in │
│ • Sophisticated cache policies │
│ │
│ Limitations: │
│ ───────────── │
│ • Requires GraphQL (obviously) │
│ • Large bundle (~35KB+) │
│ • Steep learning curve │
│ • Cache can be hard to debug │
│ • Overkill for simple GraphQL usage │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
When Apollo's Normalized Cache Shines
// The killer feature: normalized cache
// Consider this data structure:
// User appears in:
// - User profile page
// - Comment authors
// - Post authors
// - Team member lists
// - Activity feed
// With React Query/SWR (document cache):
// - Update user name
// - Need to invalidate: profile, comments, posts, teams, activity
// - Or user sees inconsistent data
// With Apollo (normalized cache):
// - Update user name
// - All places automatically update
// - Data is stored by ID, not by query
// Apollo cache structure:
const apolloCache = {
'User:123': {
id: '123',
name: 'John Doe',
email: 'john@example.com',
},
'Post:456': {
id: '456',
title: 'Hello World',
author: { __ref: 'User:123' }, // Reference, not duplicate
},
'Comment:789': {
id: '789',
body: 'Great post!',
author: { __ref: 'User:123' }, // Same reference
},
ROOT_QUERY: {
'user(id:"123")': { __ref: 'User:123' },
'post(id:"456")': { __ref: 'Post:456' },
},
};
// Update user name once:
cache.modify({
id: cache.identify(user),
fields: {
name: () => 'Jane Doe',
},
});
// All references automatically reflect the change
Apollo Architecture Patterns
// lib/apollo/client.ts
import {
ApolloClient,
InMemoryCache,
HttpLink,
split,
} from '@apollo/client';
import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
import { createClient } from 'graphql-ws';
import { getMainDefinition } from '@apollo/client/utilities';
// HTTP link for queries and mutations
const httpLink = new HttpLink({
uri: process.env.NEXT_PUBLIC_GRAPHQL_URL,
credentials: 'include',
});
// WebSocket link for subscriptions
const wsLink = typeof window !== 'undefined'
? new GraphQLWsLink(
createClient({
url: process.env.NEXT_PUBLIC_GRAPHQL_WS_URL!,
connectionParams: () => ({
authorization: getAuthToken(),
}),
})
)
: null;
// Split based on operation type
const splitLink = wsLink
? split(
({ query }) => {
const definition = getMainDefinition(query);
return (
definition.kind === 'OperationDefinition' &&
definition.operation === 'subscription'
);
},
wsLink,
httpLink
)
: httpLink;
// Type policies for cache behavior
const cache = new InMemoryCache({
typePolicies: {
Query: {
fields: {
// Pagination with cursor
posts: {
keyArgs: ['filter', 'sortBy'],
merge(existing = { edges: [] }, incoming, { args }) {
if (!args?.after) {
return incoming; // First page, replace
}
return {
...incoming,
edges: [...existing.edges, ...incoming.edges],
};
},
},
},
},
User: {
fields: {
// Computed field
fullName: {
read(_, { readField }) {
const firstName = readField<string>('firstName');
const lastName = readField<string>('lastName');
return `${firstName} ${lastName}`;
},
},
},
},
Post: {
fields: {
// Optimistic response handling
likeCount: {
merge(existing = 0, incoming) {
return incoming;
},
},
},
},
},
});
export const apolloClient = new ApolloClient({
link: splitLink,
cache,
defaultOptions: {
watchQuery: {
fetchPolicy: 'cache-and-network',
},
},
});
// hooks/use-posts.ts
import { gql, useQuery, useMutation, useSubscription } from '@apollo/client';
const GET_POSTS = gql`
query GetPosts($filter: PostFilter, $after: String, $first: Int) {
posts(filter: $filter, after: $after, first: $first) {
edges {
cursor
node {
id
title
body
author {
id
name
avatarUrl
}
likeCount
likedByMe
createdAt
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
`;
const LIKE_POST = gql`
mutation LikePost($postId: ID!) {
likePost(postId: $postId) {
id
likeCount
likedByMe
}
}
`;
const POST_UPDATED = gql`
subscription OnPostUpdated($postId: ID!) {
postUpdated(postId: $postId) {
id
title
body
likeCount
}
}
`;
export function usePosts(filter?: PostFilter) {
const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
variables: { filter, first: 20 },
notifyOnNetworkStatusChange: true,
});
const loadMore = () => {
if (data?.posts.pageInfo.hasNextPage) {
fetchMore({
variables: {
after: data.posts.pageInfo.endCursor,
},
});
}
};
return {
posts: data?.posts.edges.map(e => e.node) ?? [],
loading,
error,
hasMore: data?.posts.pageInfo.hasNextPage ?? false,
loadMore,
};
}
export function useLikePost() {
const [likePost, { loading }] = useMutation(LIKE_POST, {
// Optimistic response - instant UI update
optimisticResponse: ({ postId }) => ({
likePost: {
__typename: 'Post',
id: postId,
likeCount: 0, // Will be corrected by cache.modify
likedByMe: true,
},
}),
// Update cache before server responds
update: (cache, { data }, { variables }) => {
cache.modify({
id: cache.identify({ __typename: 'Post', id: variables?.postId }),
fields: {
likeCount: (existing) => existing + 1,
likedByMe: () => true,
},
});
},
});
return { likePost: (postId: string) => likePost({ variables: { postId } }), loading };
}
export function usePostUpdates(postId: string) {
const { data } = useSubscription(POST_UPDATED, {
variables: { postId },
});
// Subscription data automatically updates cache
return data?.postUpdated;
}
Decision Framework
The Selection Matrix
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA FETCHING DECISION MATRIX │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Start Here: What's your API? │
│ ───────────────────────────── │
│ │
│ REST/RPC API GraphQL API │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ How complex │ │ Do you need the │ │
│ │ is caching? │ │ normalized │ │
│ └──────┬──────┘ │ cache? │ │
│ │ └────────┬────────┘ │
│ ┌────┼────┐ ┌────┼────┐ │
│ ▼ ▼ ▼ ▼ ▼ │
│ Simple Med Complex Yes No │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ SWR RQ RQ+ Apollo React Query │
│ or careful or Relay + graphql-request │
│ SWR design │
│ │
│ ───────────────────────────────────────────────────────────────────── │
│ │
│ Additional Factors: │
│ │
│ Bundle size matters? │
│ • SWR (~4KB) < React Query (~13KB) < Apollo (~35KB+) │
│ │
│ Team experience? │
│ • New to data fetching → SWR │
│ • Experienced with React → React Query │
│ • GraphQL experts → Apollo │
│ │
│ Offline requirements? │
│ • React Query has best offline mutation story │
│ • Apollo has good offline support too │
│ • SWR is limited │
│ │
│ Server Components? │
│ • All work with hydration │
│ • Consider Server Components for initial load │
│ • Client library for interactivity │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
By Application Type
┌─────────────────────────────────────────────────────────────────────────────┐
│ RECOMMENDATIONS BY APP TYPE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Content Sites / Blogs / Marketing │
│ ───────────────────────────────── │
│ Primary: Server Components │
│ Secondary: SWR for interactive parts │
│ Reasoning: Mostly static, SEO important, minimal interactivity │
│ │
│ SaaS Dashboards │
│ ─────────────── │
│ Primary: React Query │
│ Secondary: Server Components for initial load │
│ Reasoning: Complex mutations, cache invalidation, real-time updates │
│ │
│ E-commerce │
│ ────────── │
│ Primary: React Query or Apollo │
│ Secondary: Server Components for catalog │
│ Reasoning: Cart state, inventory, optimistic updates │
│ │
│ Social / Collaborative Apps │
│ ─────────────────────────── │
│ Primary: Apollo (if GraphQL) or React Query │
│ Reasoning: Normalized cache valuable, complex relationships │
│ │
│ Internal Tools │
│ ────────────── │
│ Primary: React Query or SWR │
│ Reasoning: Developer speed > bundle size, forms-heavy │
│ │
│ Mobile Apps (React Native) │
│ ────────────────────────── │
│ Primary: React Query │
│ Reasoning: Offline support, good mobile perf, smaller than Apollo │
│ │
│ Real-time Heavy (Chat, Gaming) │
│ ────────────────────────────── │
│ Primary: Custom solution or Apollo subscriptions │
│ Reasoning: May need different patterns entirely (WebSockets, CRDT) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Anti-Patterns to Avoid
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA FETCHING ANTI-PATTERNS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Choosing Based on Popularity │
│ ─────────────────────────────── │
│ ❌ "React Query has more stars, so it's better" │
│ ✅ "React Query fits our cache invalidation needs" │
│ │
│ 2. GraphQL + React Query as Default │
│ ───────────────────────────────── │
│ ❌ Using GraphQL but ignoring Apollo's normalized cache │
│ ✅ If you chose GraphQL for the graph, use a graph-aware client │
│ │
│ 3. Over-engineering Simple Apps │
│ ──────────────────────────────── │
│ ❌ Apollo for a blog with 5 API calls │
│ ✅ Server Components + SWR for simple interactivity │
│ │
│ 4. Under-engineering Complex Apps │
│ ───────────────────────────────── │
│ ❌ SWR with manual cache updates everywhere │
│ ✅ React Query with proper mutation/invalidation patterns │
│ │
│ 5. Ignoring Server Components │
│ ───────────────────────────── │
│ ❌ Client-fetching everything in Next.js 14+ │
│ ✅ Server Components for initial load, client for interactivity │
│ │
│ 6. Premature Optimization │
│ ───────────────────────── │
│ ❌ "We might need normalized cache someday" │
│ ✅ Start simple, migrate when you hit real limits │
│ │
│ 7. Mixing Libraries │
│ ────────────────── │
│ ❌ React Query for some things, SWR for others, Apollo for GraphQL │
│ ✅ One primary library, consistent patterns │
│ │
│ 8. Fetching in Components Without Strategy │
│ ──────────────────────────────────────── │
│ ❌ useEffect + fetch scattered everywhere │
│ ✅ Centralized hooks with consistent patterns │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Quick Reference
Comparison At a Glance
┌─────────────────────────────────────────────────────────────────────────────┐
│ QUICK COMPARISON │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Server SWR React Apollo │
│ Comps Query │
│ ───────────────────────────────────────────────────────────────────── │
│ Bundle Size 0 KB ~4KB ~13KB ~35KB+ │
│ Learning Curve Low Low Medium High │
│ Cache Type None* URL Query-key Normalized │
│ Mutations N/A Basic Advanced Advanced │
│ DevTools N/A Basic Excellent Good │
│ Offline N/A Limited Good Good │
│ Real-time N/A Polling Polling Subscriptions │
│ TypeScript Native Good Excellent Good │
│ │
│ * Server Components use request-time caching, not client cache │
│ │
│ ───────────────────────────────────────────────────────────────────── │
│ │
│ Best For: │
│ • Server Components: SEO pages, initial data, simple apps │
│ • SWR: Simple apps, read-heavy, small teams │
│ • React Query: Complex apps, REST/RPC, most production apps │
│ • Apollo: GraphQL-native, complex relationships, large teams │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Migration Paths
┌─────────────────────────────────────────────────────────────────────────────┐
│ COMMON MIGRATION PATHS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ fetch + useState → SWR │
│ ─────────────────────── │
│ Difficulty: Easy │
│ Strategy: Replace useEffect/fetch with useSWR one component at a time │
│ │
│ SWR → React Query │
│ ────────────────── │
│ Difficulty: Medium │
│ Strategy: Similar API, add mutation patterns, update cache strategy │
│ │
│ React Query → Apollo │
│ ─────────────────── │
│ Difficulty: High │
│ Strategy: Requires GraphQL migration, fundamentally different model │
│ Consider: Do you actually need normalized cache? │
│ │
│ Any → Server Components │
│ ───────────────────── │
│ Difficulty: Medium │
│ Strategy: Move non-interactive fetches to server, keep client for UI │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Closing Thoughts
The data fetching landscape is more nuanced than feature comparisons suggest. The "best" solution depends on:
-
Your data patterns — Graph-shaped data with relationships? Consider Apollo. Document-based with complex mutations? React Query. Simple CRUD? SWR or Server Components.
-
Your team — A small team shouldn't pay the Apollo learning curve cost for a simple app. A large team with GraphQL expertise shouldn't use React Query with manual cache syncing.
-
Your trajectory — Where is your app going? Starting simple doesn't mean you can't migrate. But choosing prematurely complex means paying costs you might never need.
My default recommendations:
- Start with Server Components for everything that doesn't need client interactivity
- Add SWR or React Query for client-side needs
- Choose React Query over SWR if you need complex mutations or cache invalidation
- Choose Apollo only if you're committed to GraphQL AND need the normalized cache
- Don't mix libraries — pick one and build consistent patterns
The goal isn't to pick the "most powerful" library. It's to pick the one that makes your specific data patterns easy to work with while leaving room to grow.
Your data fetching architecture should feel obvious to the next developer who joins your team. If it requires a document to explain, you might be over-engineering.
What did you think?