Next.js Server Actions와 TanStack Query로 폼 제출 후 그리드를 자동 갱신하는 패턴

// app/items/actions.ts
// @/lib/db는 프로젝트 루트의 lib/db.ts — Prisma 또는 Drizzle 클라이언트
'use server';
 
import { db } from '@/lib/db';
 
export async function createItem(formData: FormData) {
  const name = String(formData.get('name') ?? '');
  if (!name) throw new Error('이름을 입력해주세요');
  await db.item.create({ data: { name } });
}
 
export async function getItems() {
  return db.item.findMany({ orderBy: { createdAt: 'desc' } });
}

// app/items/ItemsGrid.tsx
'use client';
 
import { useRef } from 'react';
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { getItems, createItem } from './actions';
 
export function ItemsGrid() {
  const formRef = useRef<HTMLFormElement>(null);
  const queryClient = useQueryClient();
 
  const { data: items, isLoading } = useQuery({
    queryKey: ['items'],
    queryFn: () => getItems(), // 에러는 throw로 전파 — TanStack Query가 에러 상태로 처리
  });
 
  const { mutate, isPending } = useMutation({
    mutationFn: createItem,
    onSuccess: () => {
      // Server Action 성공 확인 후 캐시 무효화 → 그리드 자동 갱신
      queryClient.invalidateQueries({ queryKey: ['items'] });
      // 성공 이후에 폼을 리셋해야 실패 시 입력값이 보존됨
      formRef.current?.reset();
    },
    onError: (error) => {
      console.error('아이템 생성 실패:', error);
    },
  });
 
  if (isLoading) return <p>로딩 중...</p>;
 
  return (
    <div>
      <form
        ref={formRef}
        onSubmit={(e) => {
          e.preventDefault();
          const formData = new FormData(e.currentTarget);
          mutate(formData);
        }}
      >
        <input name="name" placeholder="아이템 이름" required />
        <button type="submit" disabled={isPending}>
          {isPending ? '추가 중...' : '추가'}
        </button>
      </form>
 
      <table>
        <thead>
          <tr><th>이름</th><th>생성일</th></tr>
        </thead>
        <tbody>
          {items?.map((item) => (
            <tr key={item.id}>
              <td>{item.name}</td>
              <td>{new Date(item.createdAt).toLocaleDateString()}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

// lib/query-client.ts
// 주의: queryClient를 모듈 스코프에서 선언하고 MutationCache에서 참조하는 구조.
// 동일 파일에서 선언해야 순환 참조를 피할 수 있음.
import { QueryClient, MutationCache, matchQuery } from '@tanstack/react-query';
 
export const queryClient = new QueryClient({
  mutationCache: new MutationCache({
    onSuccess: (_data, _variables, _context, mutation) => {
      // meta.invalidates에 선언된 쿼리 키를 글로벌하게 자동 무효화
      queryClient.invalidateQueries({
        predicate: (query) =>
          mutation.meta?.invalidates?.some((queryKey: unknown[]) =>
            matchQuery({ queryKey }, query)
          ) ?? false,
      });
    },
  }),
});

// types/tanstack-query.d.ts
import '@tanstack/react-query';
 
declare module '@tanstack/react-query' {
  interface Register {
    mutationMeta: {
      invalidates?: unknown[][];
    };
  }
}

// mutation이 3개 이상인 프로젝트부터 이 패턴을 고려해볼 만합니다
const { mutate } = useMutation({
  mutationFn: createItem,
  meta: {
    invalidates: [['items'], ['dashboard-stats']], // onSuccess 불필요
  },
});
 
const { mutate: updateItem } = useMutation({
  mutationFn: updateItemAction,
  meta: {
    invalidates: [['items'], ['items', itemId]], // 연관 쿼리 모두 선언
  },
});

// lib/safe-action.ts — @/lib/safe-action 경로 별칭이 이 파일을 가리킴
import { createSafeActionClient } from 'next-safe-action';
 
export const actionClient = createSafeActionClient();

// app/items/actions.ts
'use server';
 
import { z } from 'zod';
import { actionClient } from '@/lib/safe-action';
import { db } from '@/lib/db';
 
const createItemSchema = z.object({
  name: z.string().min(1, '이름을 입력해주세요'),
});
 
export const createItemAction = actionClient
  .schema(createItemSchema)
  .action(async ({ parsedInput }) => {
    const item = await db.item.create({ data: parsedInput });
    return { item };
  });

// 클라이언트 컴포넌트
'use client';
 
import { useRef } from 'react';
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { mutationOptions } from '@next-safe-action/adapter-tanstack-query';
import { createItemAction } from './actions';
 
export function AddItemForm() {
  const formRef = useRef<HTMLFormElement>(null);
  const queryClient = useQueryClient();
 
  const { mutate, isPending } = useMutation(
    mutationOptions(createItemAction, {
      onSuccess: () => {
        queryClient.invalidateQueries({ queryKey: ['items'] });
        formRef.current?.reset();
      },
    })
  );
 
  return (
    <form
      ref={formRef}
      onSubmit={(e) => {
        e.preventDefault();
        const data = new FormData(e.currentTarget);
        // next-safe-action이 Zod 스키마로 타입 안전하게 처리
        mutate({ name: String(data.get('name') ?? '') });
      }}
    >
      <input name="name" required />
      <button disabled={isPending}>추가</button>
    </form>
  );
}