App Router (11) - 서버 액션 (Server Action)

2026.09.29 · 2분 읽기 · 조회 0

서버 액션

서버액션은 브라우저에서 호출할 수 있는, 서버에서 실행되는 비동기 함수이다.
기존엔 api를 통해서만 가능했던 브라우저 - 서버의 데이터 통신을, 자바스크립트 하나만으로 구현할 수 있기 때문에 굉장히 강력한 기능이다.

서버 액션을 사용하면 API 경로를 따로 만들 필요가 없어서 코드가 간결해진다.
또한 서버에서만 실행되기 때문에 데이터베이스 접근이나 민감한 데이터 처리에도 적합하다.

구현

"use server"

함수 상단이나, 별도 파일 최상단에 "use server"지시어를 명시해 사용할 수 있다.

export default function Page() {
  const createUser = async (formData: FormData) => {
    "use server";
    const name = formData.get('name')
    // 데이터베이스 저장 로직 등 서버 작업 수행
    console.log(name)
  }
 
  return (
    <form action={createUser}>
      <input type="text" name="name" />
      <button type="submit">제출</button>
    </form>
  )

다음과 같이 작성하면 createUser는 서버에서만 실행되는 함수가 된다.
해당 폼을 작성 후 제출하면 http request가 실행된다. request 헤더를 뜯어보면 Next-Action이라는 랜덤 해시값을 같이 보내준다. 이것이 하나의 api 역할을 한다.

서버액션 함수의 매개변수로 formData를 사용할 수 있는데, 브라우저 측에서 보낸 내용이 들어있다.

const name = formData.get('name')

폼데이터에서 꺼낸 값의 타입을 마우스를 올려 확인해보면 FormDataEntryValue | null 로 추론이 된다. 때문에 string타입으로 사용해야 하면

const name = formData.get('name')?.toString()

으로 string 타입으로 명시해주는 것이 좋다.

매개변수

// actions.ts
'use server'
 
// 1. 일반 객체와 숫자, 문자열 받기
export async function updateProduct(productId: number, data: { title: string; price: number }) {
  console.log(productId, data.title) 
  // DB 업데이트 로직...
}
 
// 2. 여러 개의 인자 받기
export async function deleteUser(userId: string, reason: string) {
  console.log(`Deleting ${userId} for reason: ${reason}`)
}

서버액션 함수는 브라우저에서 전달해주는 값은 모두 매개변수로 받아서 사용이 가능하다. 때문에 다양한 형태로 사용할 수 있지만, 직렬화 할 수 없는 값은 받을 수 없다.

• 불가능한 것: 리액트 컴포넌트, 일반 함수/콜백, 브라우저 DOM 엘리먼트 등
• 가능한 것: 기본 타입(String, Number, Boolean, null), 일반 객체({}), 배열([]), FormData

댓글

giscus로 동작하며 GitHub Discussions에 저장됩니다.

관련 글