Forms and Mutations

폼은 웹 어플리케이션에서 데이터를 생성하고 업데이트할 수 있게 해줍니다. Next.js는 API Routes를 사용하여 폼 제출과 데이터 변형을 처리하는 강력한 방법을 제공합니다.

알아두면 좋은 점:

곧 App Router를 점진적으로 도입하고 폼 제출 및 데이터 변형을 처리하기 위해 Server Actions 사용을 권잘할 예정입니다. Server Actions를 사용하면 API Route를 수동으로 생성할 필요 없이 컴포넌트에서 직접 호출할 수 있는 비동기 서버 함수를 정의할 수 있습니다.

API Routes는 CORS 헤더를 지정하지 않습니다 (opens in a new tab). 이는 기본적으로 동일 출처에서만 작동함을 의미합니다.

API Routes는 서버에서 실행되기 때문에 환경 변수를 통해 API 키와 같은 민감한 값을 클라이언트에 노출하지 않고 사용할 수 있습니다. 이는 어플리케이션의 보안에 매우 중요합니다.

Examples

Server-only form

Pages Router를 사용할 경우, 서버에서 데이터를 안전하게 변형하기 위해 API 엔드포인트를 수동으로 생성해야 합니다.

pages/api/submit.ts

import type { NextApiRequest, NextApiResponse } from 'next'
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  const data = req.body
  const id = await createItem(data)
  res.status(200).json({ id })
}

pages/api/submit.js

export default function handler(req, res) {
  const data = req.body
  const id = await createItem(data)
  res.status(200).json({ id })
}

그 후, 이벤트 핸들러를 사용하여 클라이언트에서 API Route를 호출합니다:

pages/index.tsx

import { FormEvent } from 'react'
 
export default function Page() {
  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
 
    const formData = new FormData(event.currentTarget)
    const response = await fetch('/api/submit', {
      method: 'POST',
      body: formData,
    })
 
    // 필요에 따라 응답 처리
    const data = await response.json()
    // ...
  }
 
  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit">Submit</button>
    </form>
  )
}

pages/index.jsx

export default function Page() {
  async function onSubmit(event) {
    event.preventDefault()
 
    const formData = new FormData(event.target)
    const response = await fetch('/api/submit', {
      method: 'POST',
      body: formData,
    })
 
    // 필요한 경우 응답 처리
    const data = await response.json()
    // ...
  }
 
  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit">Submit</button>
    </form>
  )
}

Form validation

기본적인 client-side 폼 검증을 위해 required와 type="email" 같은 HTML 검증을 사용하는 것을 권장합니다.

더 정교한 server-side 검증을 위해 zod (opens in a new tab)와 같은 스키마 검증 라이브러리를 사용하여 데이터를 변형하기 전에 필드를 검증할 수 있습니다:

pages/api/submit.ts

import type { NextApiRequest, NextApiResponse } from 'next'
import { z } from 'zod'
 
const schema = z.object({
  // ...
})
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  const parsed = schema.parse(req.body)
  // ...
}

pages/api/submit.js

import { z } from 'zod'
 
const schema = z.object({
  // ...
})
 
export default async function handler(req, res) {
  const parsed = schema.parse(req.body)
  // ...
}

Error handling

폼 제출이 실패했을 때 에러 메시지를 표시하기 위해 React state를 사용할 수 있습니다:

pages/index.tsx

import React, { useState, FormEvent } from 'react'
 
export default function Page() {
  const [isLoading, setIsLoading] = useState<boolean>(false)
  const [error, setError] = useState<string | null>(null)
 
  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    setIsLoading(true)
    setError(null) // 새 요청이 시작되면 이전 오류를 삭제
 
    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })
 
      if (!response.ok) {
        throw new Error('Failed to submit the data. Please try again.')
      }
 
      // 필요한 경우 응답 처리
      const data = await response.json()
      // ...
    } catch (error) {
      // 오류 메세지를 캡처하여 사용자에게 표시
      setError(error.message)
      console.error(error)
    } finally {
      setIsLoading(false)
    }
  }
 
  return (
    <div>
      {error && <div style={{ color: 'red' }}>{error}</div>}
      <form onSubmit={onSubmit}>
        <input type="text" name="name" />
        <button type="submit" disabled={isLoading}>
          {isLoading ? 'Loading...' : 'Submit'}
        </button>
      </form>
    </div>
  )
}

pages/index.jsx

import React, { useState } from 'react'
 
export default function Page() {
  const [isLoading, setIsLoading] = useState(false)
  const [error, setError] = useState(null)
 
  async function onSubmit(event) {
    event.preventDefault()
    setIsLoading(true)
    setError(null) // 새 요청이 시작되면 이전 오류를 삭제
 
    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })
 
      if (!response.ok) {
        throw new Error('Failed to submit the data. Please try again.')
      }
 
      // 필요한 경우 응답 처리
      const data = await response.json()
      // ...
    } catch (error) {
      // 오류 메세지를 캡처하여 사용자에게 표시
      setError(error.message)
      console.error(error)
    } finally {
      setIsLoading(false)
    }
  }
 
  return (
    <div>
      {error && <div style={{ color: 'red' }}>{error}</div>}
      <form onSubmit={onSubmit}>
        <input type="text" name="name" />
        <button type="submit" disabled={isLoading}>
          {isLoading ? 'Loading...' : 'Submit'}
        </button>
      </form>
    </div>
  )
}

Displaying loading state

서버에서 폼이 제출되는 동안 로딩 상태를 표시하기 위해 React state를 사용할 수 있습니다:

pages/index.tsx

import React, { useState, FormEvent } from 'react'
 
export default function Page() {
  const [isLoading, setIsLoading] = useState<boolean>(false)
 
  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    setIsLoading(true) // 요청이 시작되면 로딩 상태를 true로 설정
 
    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })
 
      // 필요한 경우 응답 처리
      const data = await response.json()
      // ...
    } catch (error) {
      // Handle error if necessary
      console.error(error)
    } finally {
      setIsLoading(false) // 요청이 성공적으로 끝난 경우 로딩 상태를 false로 설정
    }
  }
 
  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Loading...' : 'Submit'}
      </button>
    </form>
  )
}

pages/index.jsx

import React, { useState } from 'react'
 
export default function Page() {
  const [isLoading, setIsLoading] = useState(false)
 
  async function onSubmit(event) {
    event.preventDefault()
    setIsLoading(true) // 요청이 시작되면 로딩 상태를 true로 설정
 
    try {
      const formData = new FormData(event.currentTarget)
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: formData,
      })
 
      // 필요한 경우 응답 처리
      const data = await response.json()
      // ...
    } catch (error) {
      // Handle error if necessary
      console.error(error)
    } finally {
      setIsLoading(false) // 요청이 성공적으로 끝난 경우 로딩 상태를 false로 설정
    }
  }
 
  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Loading...' : 'Submit'}
      </button>
    </form>
  )
}

Redirecting

변형 후 사용자를 다른 라우트로 리디렉션하려는 경우, 모든 absolute URL 또는 relative URL로 redirect할 수 있습니다:

pages/api/submit.ts

import type { NextApiRequest, NextApiResponse } from 'next'
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  const id = await addPost()
  res.redirect(307, `/post/${id}`)
}

pages/api/submit.js

export default async function handler(req, res) {
  const id = await addPost()
  res.redirect(307, `/post/${id}`)
}

Setting cookies

setHeader 메서드를 사용하여 API Route 내의 쿠키를 설정할 수 있습니다:

pages/api/cookie.ts

import type { NextApiRequest, NextApiResponse } from 'next'
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  res.setHeader('Set-Cookie', 'username=lee; Path=/; HttpOnly')
  res.status(200).send('Cookie has been set.')
}

pages/api/cookie.js

export default async function handler(req, res) {
  res.setHeader('Set-Cookie', 'username=lee; Path=/; HttpOnly')
  res.status(200).send('Cookie has been set.')
}

Reading cookies

cookies를 사용하여 API Route 내의 쿠키를 읽을 수 있습니다:

pages/api/cookie.ts

import type { NextApiRequest, NextApiResponse } from 'next'
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  const auth = req.cookies.authorization
  // ...
}

pages/api/cookie.js

export default async function handler(req, res) {
  const auth = req.cookies.authorization
  // ...
}

Deleting cookies

setHeader 메서드를 사용하여 API Route 내의 쿠키를 삭제할 수 있습니다:

pages/api/cookie.ts

import type { NextApiRequest, NextApiResponse } from 'next'
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  res.setHeader('Set-Cookie', 'username=; Path=/; HttpOnly; Max-Age=0')
  res.status(200).send('Cookie has been deleted.')
}

pages/api/cookie.js

export default async function handler(req, res) {
  res.setHeader('Set-Cookie', 'username=; Path=/; HttpOnly; Max-Age=0')
  res.status(200).send('Cookie has been deleted.')
}

Get Static Paths Get Server-Side Props