サーバー機能

Reactサーバーコンポーネント

サーバー機能は、Reactサーバーコンポーネントで使用するためのものです。

注：2024年9月まで、私たちはすべてのサーバー機能を「サーバーアクション」と呼んでいました。サーバー機能がactionプロパティに渡されるか、アクションの内部から呼び出された場合、それはサーバーアクションですが、すべてのサーバー機能がサーバーアクションであるわけではありません。このドキュメントでの名称は、サーバー機能が複数の目的に使用できることを反映するように更新されました。

サーバー機能を使用すると、クライアントコンポーネントはサーバー上で実行される非同期関数を呼び出すことができます。

注

サーバー機能のサポートを構築するにはどうすればよいですか？

React 19のサーバー機能は安定しており、メジャーバージョン間で壊れることはありませんが、Reactサーバーコンポーネントのバンドラーまたはフレームワークでサーバー機能を実装するために使用される基盤となるAPIは、セマンティックバージョニングに従っておらず、React 19.xのマイナーバージョン間で壊れる可能性があります。

バンドラーまたはフレームワークとしてサーバー機能をサポートするには、特定のReactバージョンにピン留めするか、Canaryリリースを使用することをお勧めします。今後、バンドラーおよびフレームワークと協力して、サーバー機能を実装するために使用されるAPIを安定させるための作業を続けます。

サーバー機能が"use server"ディレクティブで定義されている場合、フレームワークはサーバー機能への参照を自動的に作成し、その参照をクライアントコンポーネントに渡します。その関数がクライアントで呼び出されると、Reactはサーバーにリクエストを送信して関数を実行し、結果を返します。

サーバー機能は、サーバーコンポーネントで作成してクライアントコンポーネントにプロップとして渡すことも、クライアントコンポーネントでインポートして使用することもできます。

使い方

サーバーコンポーネントからサーバー機能を作成する

サーバーコンポーネントは、"use server"ディレクティブを使用してサーバー機能を定義できます

// Server Component
import Button from './Button';

function EmptyNote () {
  async function createNoteAction() {
    // Server Function
    'use server';
    
    await db.notes.create();
  }

  return <Button onClick={createNoteAction}/>;
}

ReactがEmptyNoteサーバー機能をレンダリングすると、createNoteAction関数への参照が作成され、その参照がButtonクライアントコンポーネントに渡されます。ボタンがクリックされると、Reactは提供された参照を使用してcreateNoteAction関数を実行するためにサーバーにリクエストを送信します

"use client";

export default function Button({onClick}) { 
  console.log(onClick); 
  // {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction'}
  return <button onClick={() => onClick()}>Create Empty Note</button>
}

詳細については、"use server"のドキュメントを参照してください。

クライアントコンポーネントからサーバー機能をインポートする

クライアントコンポーネントは、"use server"ディレクティブを使用するファイルからサーバー機能をインポートできます

"use server";

export async function createNote() {
  await db.notes.create();
}

バンドラーがEmptyNoteクライアントコンポーネントをビルドすると、バンドル内のcreateNoteAction関数への参照が作成されます。buttonがクリックされると、Reactは提供された参照を使用してcreateNoteAction関数を実行するためにサーバーにリクエストを送信します

"use client";
import {createNote} from './actions';

function EmptyNote() {
  console.log(createNote);
  // {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction'}
  <button onClick={() => createNote()} />
}

詳細については、"use server"のドキュメントを参照してください。

アクション付きサーバー機能

サーバー機能は、クライアントのアクションから呼び出すことができます

"use server";

export async function updateName(name) {
  if (!name) {
    return {error: 'Name is required'};
  }
  await db.users.updateName(name);
}

"use client";

import {updateName} from './actions';

function UpdateName() {
  const [name, setName] = useState('');
  const [error, setError] = useState(null);

  const [isPending, startTransition] = useTransition();

  const submitAction = async () => {
    startTransition(async () => {
      const {error} = await updateName(name);
      if (!error) {
        setError(error);
      } else {
        setName('');
      }
    })
  }
  
  return (
    <form action={submitAction}>
      <input type="text" name="name" disabled={isPending}/>
      {state.error && <span>Failed: {state.error}</span>}
    </form>
  )
}

これにより、クライアントで Action でラップすることで、サーバー関数の isPending 状態にアクセスできます。

詳細については、<form> の外でサーバー関数を呼び出すのドキュメントを参照してください。

フォームアクションを持つサーバー関数

サーバー関数は、React 19 の新しいフォーム機能と連携します。

サーバー関数をフォームに渡すと、フォームが自動的にサーバーに送信されます。

"use client";

import {updateName} from './actions';

function UpdateName() {
  return (
    <form action={updateName}>
      <input type="text" name="name" />
    </form>
  )
}

フォームの送信が成功すると、React は自動的にフォームをリセットします。 useActionState を追加して、保留中の状態、最後のレスポンスにアクセスしたり、プログレッシブエンハンスメントをサポートしたりできます。

詳細については、フォームのサーバー関数のドキュメントを参照してください。

`useActionState` を使用したサーバー関数

アクションの保留状態と最後に返されたレスポンスへのアクセスが必要な一般的なケースでは、useActionState を使用してサーバー関数を呼び出すことができます。

"use client";

import {updateName} from './actions';

function UpdateName() {
  const [state, submitAction, isPending] = useActionState(updateName, {error: null});

  return (
    <form action={submitAction}>
      <input type="text" name="name" disabled={isPending}/>
      {state.error && <span>Failed: {state.error}</span>}
    </form>
  );
}

サーバー関数で useActionState を使用する場合、React は、ハイドレーションが完了する前に入力されたフォーム送信も自動的に再生します。これにより、ユーザーはアプリがハイドレーションされる前でもアプリを操作できます。

詳細については、useActionState のドキュメントを参照してください。

`useActionState` を使用したプログレッシブエンハンスメント

サーバー関数は、useActionState の 3 番目の引数を使用して、プログレッシブエンハンスメントもサポートします。

"use client";

import {updateName} from './actions';

function UpdateName() {
  const [, submitAction] = useActionState(updateName, null, `/name/update`);

  return (
    <form action={submitAction}>
      ...
    </form>
  );
}

パーマリンクが useActionState に提供されている場合、React は、JavaScript バンドルがロードされる前にフォームが送信された場合に、提供された URL にリダイレクトします。