React TanStack Query v5 useSuspenseQuery + ErrorBoundary: 선언적 비동기 UI 패턴 실전 적용

function UserProfile({ id }: { id: string }) {
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ['user', id],
    queryFn: () => fetchUser(id),
  });
 
  if (isLoading) return <Spinner />;
  if (isError) return <ErrorMessage message={error.message} />;
  if (!data) return null; // TypeScript를 달래기 위한 방어 코드
 
  return (
    <div className="profile">
      <h1>{data.name}</h1>
      <p>{data.email}</p>
    </div>
  );
}

function UserProfile({ id }: { id: string }) {
  const { data } = useSuspenseQuery({
    queryKey: ['user', id],
    queryFn: () => fetchUser(id),
  });
 
  // isLoading, isError, if (!data) 분기가 모두 사라졌습니다
  return (
    <div className="profile">
      <h1>{data.name}</h1>
      <p>{data.email}</p>
    </div>
  );
}

// useQuery: data는 User | undefined
const { data } = useQuery<User>({ queryKey: ['user', id], queryFn: ... });
// → data.name 접근 전에 undefined 체크 필요
 
// useSuspenseQuery: data는 항상 User
const { data } = useSuspenseQuery<User>({ queryKey: ['user', id], queryFn: ... });
// → data.name 바로 접근 가능 — 컴파일러와 런타임 모두 안전

// throwOnError: true를 사용하는 경우
const { data, isLoading } = useQuery({
  queryKey: ['user', id],
  queryFn: () => fetchUser(id),
  throwOnError: true,
});
// data는 여전히 User | undefined
// isLoading 분기와 undefined 체크가 여전히 필요합니다

import { skipToken, useSuspenseQuery } from '@tanstack/react-query';
 
function UserProfile({ id }: { id: string | null }) {
  const { data } = useSuspenseQuery({
    queryKey: ['user', id],
    queryFn: id ? () => fetchUser(id) : skipToken, // id가 없으면 쿼리 skip
  });
 
  return <div>{data.name}</div>;
}

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
import { Suspense } from 'react';
 
function UserProfilePage({ id }: { id: string }) {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          FallbackComponent={({ error, resetErrorBoundary }) => (
            <div>
              <p>오류가 발생했어요: {error.message}</p>
              <button onClick={resetErrorBoundary}>다시 시도</button>
            </div>
          )}
        >
          <Suspense fallback={<ProfileSkeleton />}>
            <UserProfile id={id} />
          </Suspense>
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

import { useSuspenseQuery, QueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
import { Suspense } from 'react';
 
// 재사용 가능한 에러 폴백 컴포넌트
function ErrorFallback({
  error,
  resetErrorBoundary,
}: {
  error: Error;
  resetErrorBoundary: () => void;
}) {
  return (
    <div role="alert" className="error-container">
      <p>오류가 발생했어요: {error.message}</p>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  );
}
 
// ✅ 성공 상태만 집중하는 컴포넌트
function UserProfile({ id }: { id: string }) {
  const { data } = useSuspenseQuery({
    queryKey: ['user', id],
    queryFn: () => fetchUser(id),
  });
 
  return (
    <div className="profile">
      <h1>{data.name}</h1>
      <p>{data.email}</p>
    </div>
  );
}
 
// ✅ 로딩·에러 경계를 선언하는 상위 컴포넌트
function UserProfilePage({ id }: { id: string }) {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary onReset={reset} FallbackComponent={ErrorFallback}>
          <Suspense fallback={<ProfileSkeleton />}>
            <UserProfile id={id} />
          </Suspense>
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
import { Suspense } from 'react';
 
function Dashboard() {
  return (
    <div className="dashboard">
      {/* 헤더는 독립적으로 로딩·에러 처리 */}
      <QueryErrorResetBoundary>
        {({ reset }) => (
          <ErrorBoundary onReset={reset} FallbackComponent={ErrorFallback}>
            <Suspense fallback={<HeaderSkeleton />}>
              <Header />
            </Suspense>
          </ErrorBoundary>
        )}
      </QueryErrorResetBoundary>
 
      <div className="grid grid-cols-2 gap-4">
        {/* 통계와 피드는 서로 독립적 */}
        <QueryErrorResetBoundary>
          {({ reset }) => (
            <ErrorBoundary onReset={reset} FallbackComponent={ErrorFallback}>
              <Suspense fallback={<StatsSkeleton />}>
                <StatsPanel />
              </Suspense>
            </ErrorBoundary>
          )}
        </QueryErrorResetBoundary>
 
        <QueryErrorResetBoundary>
          {({ reset }) => (
            <ErrorBoundary onReset={reset} FallbackComponent={ErrorFallback}>
              <Suspense fallback={<FeedSkeleton />}>
                <ActivityFeed />
              </Suspense>
            </ErrorBoundary>
          )}
        </QueryErrorResetBoundary>
      </div>
    </div>
  );
}

import { useSuspenseQueries } from '@tanstack/react-query';
 
function ProductDetail({ id }: { id: string }) {
  const [{ data: product }, { data: reviews }] = useSuspenseQueries({
    queries: [
      {
        queryKey: ['product', id],
        queryFn: () => fetchProduct(id),
      },
      {
        queryKey: ['reviews', id],
        queryFn: () => fetchReviews(id),
      },
    ],
  });
 
  // product, reviews 모두 항상 정의된 값
  return (
    <div>
      <h1>{product.title}</h1>
      <p>{product.description}</p>
      <ReviewList reviews={reviews} />
    </div>
  );
}

// app/users/[id]/page.tsx (Next.js 14 기준)
import { Suspense } from 'react';
import { UserDetail } from './UserDetail';
import { UserSkeleton } from './UserSkeleton';
 
export default function UserPage({
  params,
}: {
  // Next.js 15+에서는 params가 Promise<{ id: string }>로 변경됨
  // 사용 중인 Next.js 버전을 반드시 확인해보시는 것이 좋습니다
  params: { id: string };
}) {
  return (
    // HTML 스트리밍: Suspense 경계 단위로 청크가 전송됨
    <Suspense fallback={<UserSkeleton />}>
      <UserDetail id={params.id} />
    </Suspense>
  );
}