フォームとミューテーション

フォームはウェブアプリケーションでデータを作成および更新するための手段です。Next.jsはAPIルートを使用してフォーム送信とデータ変更を処理する強力な方法を提供します。

補足:

近々、App Routerへの漸進的な移行とサーバーアクションを使用したフォーム送信とデータ変更の処理を推奨する予定です。サーバーアクションにより、明示的にAPIルートを作成せずに、コンポーネントから直接呼び出せる非同期サーバー関数を定義できます。

APIルートはCORSヘッダーを指定しないため、デフォルトで同一オリジンのみとなります。

APIルートはサーバー上で実行されるため、環境変数を介して、クライアントに公開せずに機密値（APIキーなど）を使用できます。これはアプリケーションのセキュリティにとって重要です。

例

サーバー専用のフォーム

Pagesルーターでは、サーバー上でデータを安全に変更する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ルートを呼び出します：

pages/index.tsx

TypeScript

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">送信</button>
    </form>
  )
}

フォームバリデーション

基本的なクライアントサイドのフォームバリデーションには、requiredやtype="email"などのHTML検証を推奨します。

より高度なサーバーサイドのバリデーションには、zodのようなスキーマバリデーションライブラリを使用して、データを変更する前にフォームフィールドを検証できます：

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)
  // ...
}

エラー処理

フォーム送信が失敗した場合にエラーメッセージを表示するには、Reactの状態を使用できます：

pages/index.tsx

TypeScript

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('データの送信に失敗しました。もう一度お試しください。')
      }
 
      // 必要に応じてレスポンスを処理
      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 ? '読み込み中...' : '送信'}
        </button>
      </form>
    </div>
  )
}

読み込み状態の表示

サーバーでフォームが送信されている間、読み込み状態を表示するにはReactの状態を使用できます：

pages/index.tsx

TypeScript

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) // リクエストが開始されたときにloadingを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) {
      // 必要に応じてエラーを処理
      console.error(error)
    } finally {
      setIsLoading(false) // リクエストが完了したときにloadingをfalseに設定
    }
  }
 
  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" />
      <button type="submit" disabled={isLoading}>
        {isLoading ? '読み込み中...' : '送信'}
      </button>
    </form>
  )
}

リダイレクト

ミューテーション後にユーザーを別のルートにリダイレクトする場合、任意の絶対・相対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}`)
}

Cookieの設定

APIルート内でレスポンスのsetHeaderメソッドを使用してCookieを設定できます：

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が設定されました。')
}

pages/api/cookie.js

export default async function handler(req, res) {
  res.setHeader('Set-Cookie', 'username=lee; Path=/; HttpOnly')
  res.status(200).send('Cookieが設定されました。')
}

Cookieの読み取り

APIルート内でcookiesリクエストヘルパーを使用してCookieを読み取ることができます：

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
  // ...
}

Cookieの削除

APIルート内でレスポンスのsetHeaderメソッドを使用してCookieを削除できます：

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が削除されました。')
}

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が削除されました。')
}