はじめに
Next.js の App Router では、Server Actions を使うとフォーム送信やデータ更新を API Route なしで書けます。とても便利な反面、
-
'use server'はコンポーネント内に書くべき?actions.tsに分けるべき? -
'use server'とserver-onlyは何が違うの? - 「Server Actions は公開エンドポイント」と言われるけど、何に気をつければいい?
といった点で迷う人も多いと思います。
本記事では、Server Actions の 2 つの書き方(インライン / ファイル分割) を紹介したうえで、server-only を使った Data Access Layer(DAL)による安全な構成を解説します。
本記事は Next.js 16.3 時点の公式ドキュメントに基づいています。
Server Actions とは
Server Actions は、クライアントから呼び出せるサーバー側の非同期関数です。関数の先頭またはファイルの先頭に 'use server' を書くと、Next.js がその関数を呼び出すための仕組みを自動で作ってくれます。
async function createPost(formData: FormData) {
'use server'
// ここはサーバーで実行される
await db.post.create({ data: { title: formData.get('title') as string } })
}
裏側では、Server Action ごとに POST リクエストで呼び出せるエンドポイントが作られます。この事実は後半のセキュリティの話で重要になるので、覚えておいてください。
React の公式ドキュメントでは、'use server' を付けた関数全般を Server Functions と呼び、そのうちフォームの action などで使われるものを Server Actions と呼んでいます。本記事では慣例に合わせて Server Actions と書きます。
パターン1:Server Component にインラインで書く
Server Component の中で、関数本体の先頭に 'use server' を書くパターンです。
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
import { db } from '@/lib/db'
export default function NewPostPage() {
async function createPost(formData: FormData) {
'use server'
const title = formData.get('title') as string
await db.post.create({ data: { title } })
revalidatePath('/posts')
redirect('/posts')
}
return (
<form action={createPost}>
<input name="title" />
<button type="submit">作成</button>
</form>
)
}
メリット
- UI と処理が 1 ファイルにまとまるので、小さな機能なら読みやすい
- クロージャが使える:レンダリング時の値を Server Action の中で参照できる
export default async function Page() {
const publishVersion = await getLatestVersion()
async function publish() {
'use server'
// レンダリング時点のバージョンと比較できる
if (publishVersion !== (await getLatestVersion())) {
throw new Error('公開ボタンを押した後にバージョンが変わりました')
}
// ...
}
return (
<form>
<button formAction={publish}>公開</button>
</form>
)
}
デメリット・注意点
-
Client Component の中で直接定義することはできません。
'use client'のファイルでインラインの'use server'を書くとエラーになります。Client Component で使いたい場合は、後述のactions.tsに分けて import するか、Server Component で定義して props で渡します - 他のページから再利用できない
props で渡す場合は、次のように書きます。
import { PostForm } from './post-form'
export default function NewPostPage() {
async function createPost(formData: FormData) {
'use server'
// ...
}
return <PostForm action={createPost} />
}
'use client'
export function PostForm({
action,
}: {
action: (formData: FormData) => Promise<void>
}) {
return (
<form action={action}>
<input name="title" />
<button type="submit">作成</button>
</form>
)
}
- クロージャで参照した変数は、一度クライアントに送られてからサーバーに戻ってきます。Next.js は自動で暗号化していますが、公式ドキュメントでも「暗号化だけに頼って機密情報を守ることは推奨しない」とされています
クロージャで参照した値は暗号化されてクライアントとやり取りされます。API キーやユーザーの個人情報のような機密情報をクロージャで参照するのは避けましょう。
パターン2:actions.ts に分けて書く
ファイルの先頭に 'use server' を書き、Server Action だけをまとめるパターンです。
'use server'
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
import { db } from '@/lib/db'
export async function createPost(formData: FormData) {
const title = formData.get('title') as string
await db.post.create({ data: { title } })
revalidatePath('/posts')
redirect('/posts')
}
Server Component からも Client Component からも import して使えます。
import { createPost } from '../actions'
export default function NewPostPage() {
return (
<form action={createPost}>
<input name="title" />
<button type="submit">作成</button>
</form>
)
}
Client Component からも、同じように import するだけで呼び出せます。
'use client'
import { createPost } from '../actions'
export function PostForm() {
return (
<form action={createPost}>
<input name="title" />
<button type="submit">作成</button>
</form>
)
}
実務では、バリデーションエラーや送信中の状態を扱うために useActionState と組み合わせるのが定番です。完全な例は後半で紹介します。
メリット
-
Client Component から呼び出せる(
useActionState、onClickなど) - 複数のページで再利用できる
- 「サーバーへの入口」が 1 か所にまとまるので、セキュリティレビューがしやすい
注意点:export した関数はすべて公開エンドポイントになる
'use server' ファイルで export した async 関数は、すべて Server Action として扱われます。
'use server'
export async function createPost(formData: FormData) { /* ... */ }
// ⚠️ ただのヘルパーのつもりでも、Server Action として扱われる
export async function getPostsByUserId(userId: string) {
return db.post.findMany({ where: { userId } })
}
このように、ヘルパー関数や DB アクセス関数を 'use server' ファイルに置くのは危険です。
Next.js には、使われていない Server Action を削除する仕組み(dead code elimination)や、推測されにくい ID を付ける仕組みがあります。ただし公式ドキュメントでも「Server Action は直接 POST で呼ばれうるものとして扱い、中で必ず認証・認可をすること」と明記されています。これらの仕組みに頼らず、'use server' ファイルには「クライアントから呼ばれてよい関数」だけを置くのが鉄則です。
どちらを使うべきか
| インライン |
actions.ts に分割 |
|
|---|---|---|
| 書く場所 | Server Component の中 | 専用ファイル |
| Client Component から使う | △(props で渡せば可) | ✅(直接 import できる) |
| 再利用 | ❌ | ✅ |
| クロージャ | ✅ | ❌(引数で渡す) |
| 向いている用途 | 小さな単発のフォーム、プロトタイプ | ほとんどの実務コード |
実務では actions.ts に分けるパターンを基本にするのがおすすめです。Client Component と組み合わせることが多く、入口が 1 か所にまとまっているほうが安全性も保ちやすいからです。
インラインは、「このページでしか使わない小さな処理」や「クロージャでレンダリング時の値を使いたい」場合に限定するとよいでしょう。
'use server' と server-only の違い
ここが一番混乱しやすいポイントです。名前は似ていますが、意味はほぼ逆です。
'use server' |
server-only |
|
|---|---|---|
| 書き方 | ディレクティブ(文字列) | パッケージの import |
| 意味 | クライアントから呼べるようにする | クライアントに絶対に含めない |
| 役割 | サーバーへの入口を開ける | サーバー専用コードを守る |
| 付ける対象 | Server Action | DB アクセス、秘密鍵を扱う処理など |
'use server' // → この関数はクライアントから呼べるようになる
import 'server-only' // → このファイルを Client Component から import したらビルドエラー
'use server' は「クライアントに公開する」ための宣言なので、DB アクセスなどの内部処理に付けてはいけません。内部処理には server-only を付けて守ります。
server-only の導入
npm install server-only
import 'server-only'
import { PrismaClient } from '@prisma/client'
export const db = new PrismaClient()
この状態で、誤って Client Component から lib/db.ts を import するとビルドエラーになり、DB クライアントや秘密情報がブラウザ向けのバンドルに入るのを防げます。
Next.js は server-only の import を内部で処理するため、厳密にはパッケージのインストールは必須ではありません。ただし lint の「未宣言の依存」ルールに引っかかることがあるので、インストールしておくのが無難です。
server-only を使った安全な書き方(Data Access Layer)
公式ドキュメントでは、新規プロジェクトには Data Access Layer(DAL) の導入が推奨されています。役割ごとにファイルを分けるのがポイントです。
src/
├── lib/
│ └── db.ts # 'server-only':DB クライアント
├── data/ # 'server-only':Data Access Layer
│ ├── auth.ts # セッションの取得・検証
│ └── posts.ts # 認可チェック + DB 操作 + DTO への変換
└── app/
└── posts/
├── actions.ts # 'use server':入力の検証 → DAL の呼び出し → 再検証
├── page.tsx
└── new/
└── post-form.tsx # 'use client'
| 層 | ディレクティブ | 責務 |
|---|---|---|
app/**/actions.ts |
'use server' |
入口:入力を検証し、DAL を呼び、キャッシュを更新する |
data/*.ts |
import 'server-only' |
中核:認証・認可、DB 操作、返す値の絞り込み |
lib/db.ts |
import 'server-only' |
基盤:DB クライアント、環境変数へのアクセス |
1. 認証(data/auth.ts)
import 'server-only'
import { cache } from 'react'
import { cookies } from 'next/headers'
import { redirect } from 'next/navigation'
import { decrypt } from '@/lib/session'
// cache() で 1 リクエスト内の重複呼び出しをまとめる
export const verifySession = cache(async () => {
const cookieStore = await cookies()
const session = await decrypt(cookieStore.get('session')?.value)
if (!session?.userId) {
redirect('/login')
}
return { userId: session.userId as string }
})
2. DAL(data/posts.ts)
認証・認可・DB 操作・返す値の絞り込みをここに集約します。
import 'server-only'
import { db } from '@/lib/db'
import { verifySession } from './auth'
export async function createPost(input: { title: string; body: string }) {
const { userId } = await verifySession()
const post = await db.post.create({
data: { ...input, authorId: userId },
})
// DB のレコードをそのまま返さず、必要な値だけ返す(DTO)
return { id: post.id }
}
export async function deletePost(postId: string) {
const { userId } = await verifySession()
const post = await db.post.findUnique({ where: { id: postId } })
if (!post) {
throw new Error('Not Found')
}
// 認可:ログインしているかだけでなく「その投稿の持ち主か」を確認する
if (post.authorId !== userId) {
throw new Error('Forbidden')
}
await db.post.delete({ where: { id: postId } })
}
3. Server Action(app/posts/actions.ts)
Server Action は薄く保ちます。入力の検証を行い、DAL を呼び、キャッシュを更新するだけです。
'use server'
import { z } from 'zod'
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
import * as postsDal from '@/data/posts'
const CreatePostSchema = z.object({
title: z.string().trim().min(1, 'タイトルは必須です').max(100, 'タイトルは100文字以内です'),
body: z.string().trim().min(1, '本文は必須です'),
})
export type CreatePostState = {
errors?: { title?: string[]; body?: string[] }
} | null
export async function createPostAction(
_prevState: CreatePostState,
formData: FormData,
): Promise<CreatePostState> {
// 1. 入力の検証(クライアントからの値は信用しない)
const result = CreatePostSchema.safeParse({
title: formData.get('title'),
body: formData.get('body'),
})
if (!result.success) {
return { errors: z.flattenError(result.error).fieldErrors }
}
// 2. 認証・認可・DB 操作は DAL に任せる
const { id } = await postsDal.createPost(result.data)
// 3. キャッシュを更新して遷移
revalidatePath('/posts')
redirect(`/posts/${id}`)
}
export async function deletePostAction(postId: string) {
// 引数もクライアントから改ざんできるので検証する
const id = z.uuid().parse(postId)
await postsDal.deletePost(id)
revalidatePath('/posts')
}
4. Client Component(post-form.tsx)
'use client'
import { useActionState } from 'react'
import { createPostAction } from '../actions'
export function PostForm() {
const [state, formAction, isPending] = useActionState(createPostAction, null)
return (
<form action={formAction}>
<input name="title" />
{state?.errors?.title && <p>{state.errors.title[0]}</p>}
<textarea name="body" />
{state?.errors?.body && <p>{state.errors.body[0]}</p>}
<button type="submit" disabled={isPending}>
{isPending ? '投稿中...' : '投稿する'}
</button>
</form>
)
}
この構成のうれしいところ
-
server-onlyのおかげで、DB クライアントや DAL がクライアントのバンドルに混入しない(混入しそうになるとビルドエラー) - 認証・認可が DAL に集約されるので、Server Action を追加しても認証チェックを書き忘れにくい
- Server Action が薄いので、「どの入口で何を受け付けているか」をレビューしやすい
- DAL は Server Component からのデータ取得にも使い回せる
公式ドキュメントによると、'use server' ファイル自体に import 'server-only' を書いても問題ありません。'use server' のモジュールはサーバー専用の層で解決されるため、Client Component から import してもビルドエラーにはなりません。
セキュリティチェックリスト
Server Action を書くときは、次の項目を確認しましょう。
✅ 入力を検証しているか
FormData も引数も、クライアントからいくらでも改ざんできます。zod などで必ず検証しましょう。TypeScript の型はビルド時のチェックにすぎず、実行時には何も保証しません。
✅ Server Action の中で認証しているか
ページ側で認証チェックをしていても、Server Action は守られません。Server Action はページとは別の入口なので、それぞれの中で必ず再検証します。
export default async function AdminPage() {
const session = await auth()
if (!session?.user?.isAdmin) redirect('/login') // ← ページの表示を制御するだけ
return (
<form
action={async () => {
'use server'
// ← ここでも必ずチェックする(ページのチェックはここには効かない)
const session = await auth()
if (!session?.user?.isAdmin) throw new Error('Unauthorized')
await db.record.deleteMany()
}}
>
<button>全削除</button>
</form>
)
}
✅ 認可(リソースの持ち主か)を確認しているか
「ログインしているか」だけでなく、「そのユーザーがそのリソースを操作してよいか」も確認します。これを怠ると、他人の投稿 ID を送るだけで削除できてしまう IDOR(Insecure Direct Object Reference) の脆弱性になります。
✅ 戻り値を絞っているか
Server Action の戻り値はシリアライズされてクライアントに送られます。DB のレコードをそのまま返すと、パスワードのハッシュや内部用のフィールドまで漏れる可能性があります。
// ❌ レコード全体を返す
return db.user.update({ where: { id }, data })
// ✅ 必要な値だけ返す
await db.user.update({ where: { id }, data })
return { success: true }
✅ 'use server' ファイルに余計な export がないか
ヘルパー関数や DB アクセス関数は server-only のファイルに移しましょう。
✅ 環境変数へのアクセスを DAL に限定しているか
公式ドキュメントでも、process.env にアクセスするのは DAL だけにすることが推奨されています。
✅ 重い処理にレート制限をかけているか
メール送信など負荷やコストのかかる処理は、直接 POST で連打される可能性があります。必要に応じてレート制限を入れましょう。
CSRF 対策として、Next.js は Server Action を POST に限定し、さらに Origin ヘッダーと Host ヘッダーを比較しています。リバースプロキシ越しにアクセスする構成では、next.config.js の experimental.serverActions.allowedOrigins で許可するオリジンを指定します。
まとめ
- インライン:Server Component 内で手軽に書ける。クロージャが使えるが、Client Component 内では定義できない(props で渡せば使える)
-
actions.tsに分割:Client Component から使え、再利用もできる。実務ではこちらが基本 - **
'use server'は「クライアントに公開する」、server-onlyは「クライアントに含めない」**で、意味はほぼ逆 -
'use server'のファイルは入口として薄く保ち、認証・認可・DB 操作はserver-onlyの DAL に集約する - Server Action は公開された POST エンドポイントだと考え、入力の検証・認証・認可・戻り値の絞り込みを徹底する
Server Actions は API Route を書かずに済む便利な機能ですが、「関数を呼んでいる」感覚のまま書くと、公開エンドポイントであることを忘れがちです。server-only と DAL を組み合わせて、安全な構成にしておきましょう。