Next.js Server Actions를 사용하면 간단한 폼 구현 시 API 라우트를 생략할 수 있습니다

Next.js를 통해 이제 개발자는 컴포넌트에서 서버 전용 함수를 직접 호출할 수 있으며, 이를 통해 폼 제출과 같은 일상적인 작업을 위해 별도의 API 라우트를 생성할 필요가 없어졌습니다. 새로운 Server Actions 기능을 사용하면 단일 HTML 폼이 중간 fetch 호출 없이 백엔드 코드를 트리거할 수 있어, 보일러플레이트 코드를 줄이고 프론트엔드와 백엔드 간의 계약을 더욱 긴밀하게 만듭니다.

기존 방식이 무겁게 느껴지는 이유

일반적인 React 또는 Next.js 앱에서 간단한 "프로젝트 생성" 폼은 일련의 단계를 거칩니다. API 라우트 파일, 브라우저에서의 fetch 요청, 로딩 및 에러 상태 처리, CORS 헤더, 그리고 마지막으로 새로운 데이터를 반영하기 위한 클라이언트 측 업데이트까지 말이죠. 각 단계는 파일과 코드 라인을 늘리고 오류 발생 지점을 추가합니다. 팀은 단순히 데이터베이스에 레코드를 기록하는 것이 목적일 때조차 이러한 요소들을 서로 연결하는 데 시간을 소비합니다.

Server Actions로 간극을 좁히다

Server Actions는 서버에서만 실행됨이 보장되는 비동기 함수입니다. 파일 상단에 "use server" 지시어를 추가하면 컴파일러가 해당 코드를 브라우저 번들에서 제외하도록 지시하므로, 데이터베이스, 비밀 정보 또는 기타 서버 전용 리소스에 안전하게 접근할 수 있습니다. 함수가 서버에 존재하기 때문에, 컴포넌트는 네이티브 <form> 요소의 action 속성을 통해 이를 직접 호출할 수 있습니다.

액션 정의하기

export async function createProject(formData: FormData) {
  const title = formData.get('title') as string;

  if (!title) throw new Error('Title is required');

  await db.project.create({
    data: { title }
  });

  revalidatePath('/dashboard');
}

이 함수는 FormData 객체를 전달받아 페이로드를 검증하고 데이터베이스에 기록한 다음, Next.js에 /dashboard 페이지를 새로고침하도록 요청하여 전체 페이지 리로드 없이 UI에 새로운 프로젝트가 표시되도록 합니다.

UI에 연결하기

export default function NewProjectForm() {
  return (
    <form action={createProject}>
      <input type="text" name="title" required />
      <SubmitButton />
    </form>
  );
}

사용자가 제출 버튼을 클릭하면 브라우저는 폼 데이터를 서버 측 createProject 함수로 전송(post)합니다. 이는 표준 HTML 폼 동작을 사용하므로 JavaScript가 아직 로드되지 않은 상태에서도 제출이 가능하며, 느린 연결 환경에서 체감 성능을 향상시킵니다.

팀이 얻는 이점

• 파일 수 감소 – 각 엔드포인트마다 별도의 pages/api 또는 app/api 파일이 필요하지 않습니다.
• 연결 작업 감소 – 수동 fetch 호출이나 명시적인 CORS 처리가 필요 없습니다.
• 내장된 타입 안정성 – 함수 시그니처가 서버와 클라이언트 간에 공유되므로 TypeScript가 불일치를 조기에 발견할 수 있습니다.
• 성능 우위 – 요청이 서버 함수로 직접 전달되어, 클라이언트 측 fetch가 유발하는 추가적인 네트워크 홉(network hop)을 건너뜁니다.

한계 및 주의 사항

Server Actions는 아직 초기 단계의 기능입니다. "use server"로 표시된 비동기 함수만 사용할 수 있으며, 클라이언트에 임의의 JavaScript 객체를 반환할 수 없습니다. 반드시 리다이렉트(redirect), 재검증(revalidation) 또는 일반 응답(plain response)으로 종료되어야 합니다. 호출 스택이 브라우저에서 서버 런타임으로 점프하기 때문에 디버깅 방식이 다르게 느껴질 수 있으며, 이는 기존 API 라우트 로그에 익숙한 개발자들에게 생소할 수 있습니다. 또한, 여러 마이크로서비스가 포함되거나 세밀한 HTTP 상태 코드가 필요한 복잡한 워크플로우에는 여전히 전통적인 API 엔드포인트가 필요할 수 있습니다.

주목해야 할 점

Next.js는 향후 릴리스에서 더 많은 응답 유형을 지원하고 도구 통합을 개선하는 등 Server Actions API를 확장할 가능성이 높습니다. 초기 도입자들은 미션 크리티컬(mission-critical)한 기능을 이 방식으로 전환하기 전에 프레임워크의 변경 로그와 커뮤니티 피드백을 확인하여 안정성을 가늠해야 합니다. 또한 번들 크기와 서버 렌더링 지표를 모니터링하면 클라이언트 코드 감소가 특정 트래픽 패턴에서 측정 가능한 지연 시간(latency) 이득으로 이어지는지 확인할 수 있습니다.

결론

컴포넌트가 서버 전용 함수를 직접 호출할 수 있게 함으로써, Next.js Server Actions는 오랫동안 React 프로젝트를 복잡하게 만들었던 중간 매개체를 제거합니다. 그 결과, 기능의 현재 제약 사항이 프로젝트의 요구 사항과 일치한다면 더 깔끔한 코드, 더 빠른 왕복 시간(round-trip), 그리고 더 매끄러운 개발자 경험을 얻을 수 있습니다.