next-safe-action은(는) 무엇을 하나요?
개요
next-safe-action은 Next.js Server Action에 타입 안전성, 입력 검증, 미들웨어를 추가합니다. FormData를 수동으로 파싱하고 오류를 처리하는 대신 Zod 스키마를 정의하면 자동으로 검증되고 타입이 지정된 입력과 오류 처리를 얻을 수 있습니다.
사용 방법
1단계: 설정
npm install next-safe-action zod
// lib/safe-action.ts — 인증 미들웨어를 포함한 액션 클라이언트
import { createSafeActionClient } from 'next-safe-action'
import { auth } from '@/auth'
// 공개 액션 (인증 불필요)
export const publicAction = createSafeActionClient()
// 인증된 액션
export const authAction = createSafeActionClient({
async middleware() {
const session = await auth()
if (!session?.user) throw new Error('인증되지 않음')
return { user: session.user }
},
})
2단계: 액션 정의
// actions/projects.ts — 타입 안전한 서버 액션
'use server'
import { authAction } from '@/lib/safe-action'
import { z } from 'zod'
import { prisma } from '@/lib/db'
import { revalidatePath } from 'next/cache'
const createProjectSchema = z.object({
name: z.string().min(1).max(100),
description: z.string().max(500).optional(),
})
export const createProject = authAction
.schema(createProjectSchema)
.action(async ({ parsedInput, ctx }) => {
const project = await prisma.project.create({
data: {
...parsedInput,
ownerId: ctx.user.id,
},
})
revalidatePath('/dashboard')
return { project }
})
const updateProjectSchema = z.object({
id: z.string().uuid(),
name: z.string().min(1).max(100).optional(),
description: z.string().max(500).optional(),
status: z.enum(['active', 'archived']).optional(),
})
export const updateProject = authAction
.schema(updateProjectSchema)
.action(async ({ parsedInput, ctx }) => {
const { id, ...data } = parsedInput
// 소유권 확인
const project = await prisma.project.findFirst({
where: { id, ownerId: ctx.user.id },
})
if (!project) throw new Error('프로젝트를 찾을 수 없음')
const updated = await prisma.project.update({
where: { id },
data,
})
revalidatePath(`/projects/${id}`)
return { project: updated }
})
3단계: 컴포넌트에서 사용
// components/CreateProjectForm.tsx — 안전한 액션을 사용한 폼
'use client'
import { useAction } from 'next-safe-action/hooks'
import { createProject } from '@/actions/projects'
export function CreateProjectForm() {
const { execute, result, isExecuting } = useAction(createProject)
return (
<form action={execute}>
<input name="name" placeholder="프로젝트 이름" required />
<textarea name="description" placeholder="설명 (선택 사항)" />
{result.validationErrors && (
<div className="errors">
{Object.entries(result.validationErrors).map(([field, errors]) => (
<p key={field}>{field}: {errors?.join(', ')}</p>
))}
</div>
)}
{result.serverError && (
<p className="error">{result.serverError}</p>
)}
<button disabled={isExecuting}>
{isExecuting ? '생성 중...' : '프로젝트 생성'}
</button>
</form>
)
}
지침
- 항상 Zod 스키마를 사용하여 입력을 검증하세요 — 클라이언트가 제출한 데이터를 절대 신뢰하지 마세요.
- 인증을 위해 미들웨어를 사용하세요 — 체인의 모든 액션보다 먼저 실행됩니다.
useAction훅은isExecuting,result, 자동 오류 처리를 제공합니다.- 즉각적인 UI 피드백을 위해
useOptimisticAction과 함께 사용하세요. - 데이터베이스와 UI를 동기화하기 위해 변이 후 경로/태그를 재검증하세요.