Funções do Servidor

Quando uma Função do Servidor é definida com a diretiva "use server", seu framework criará automaticamente uma referência à função do servidor e passará essa referência para o Componente Cliente. Quando essa função for chamada no cliente, o React enviará uma requisição para o servidor para executar a função e retornará o resultado.

As Funções do Servidor podem ser criadas em Componentes do Servidor e passadas como props para Componentes Cliente, ou podem ser importadas e usadas em Componentes Cliente.

Uso

Criando uma Função do Servidor de um Componente do Servidor

Componentes do Servidor podem definir Funções do Servidor com a diretiva "use server":

// Componente do Servidor
import Button from './Button';

function EmptyNote () {
  async function createNoteAction() {
    // Função do Servidor
    'use server';
    
    await db.notes.create();
  }

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

Quando o React renderiza a Função do Servidor EmptyNote, ele criará uma referência à função createNoteAction e passará essa referência para o Componente Cliente Button. Quando o botão for clicado, o React enviará uma requisição para o servidor para executar a função createNoteAction com a referência fornecida:

"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>
}

Para mais informações, consulte a documentação para "use server".

Importando Funções do Servidor de Componentes Cliente

Componentes Cliente podem importar Funções do Servidor de arquivos que usam a diretiva "use server":

"use server";

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

Quando o bundler constrói o Componente Cliente EmptyNote, ele criará uma referência à função createNote no bundle. Quando o button for clicado, o React enviará uma requisição para o servidor para executar a função createNote usando a referência fornecida:

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

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

Para mais informações, consulte a documentação para "use server".

Funções do Servidor com Ações

Funções do Servidor podem ser chamadas de Ações no cliente:

"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>
  )
}

Isso permite que você acesse o estado isPending da Função do Servidor, encapsulando-a em uma Ação no cliente.

Para mais informações, consulte a documentação para Chamando uma Função do Servidor fora de <form>

Funções do Servidor com Ações de Formulário

Funções do Servidor funcionam com os novos recursos de Formulário no React 19.

Você pode passar uma Função do Servidor para um Formulário para automaticamente enviar o formulário ao servidor:

"use client";

import {updateName} from './actions';

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

Quando a submissão do Formulário for bem-sucedida, o React redefinirá automaticamente o formulário. Você pode adicionar useActionState para acessar o estado pendente, a última resposta ou para oferecer suporte a aprimoramento progressivo.

Para mais informações, consulte a documentação para Funções do Servidor em Formulários.

Funções do Servidor com useActionState

Você pode chamar Funções do Servidor com useActionState para o caso comum em que você só precisa acessar o estado pendente da ação e a última resposta retornada:

"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>
  );
}

Ao usar useActionState com Funções do Servidor, o React também reproduzirá automaticamente as submissões de formulário inseridas antes que a hidratação termine. Isso significa que os usuários podem interagir com seu aplicativo mesmo antes que o aplicativo tenha hidratado.

Para mais informações, consulte a documentação para useActionState.

Aprimoramento progressivo com useActionState

Funções do Servidor também oferecem suporte a aprimoramento progressivo com o terceiro argumento de useActionState.

"use client";

import {updateName} from './actions';

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

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

Quando o permalink for fornecido para useActionState, o React redirecionará para a URL fornecida se o formulário for enviado antes que o bundle JavaScript seja carregado.

Para mais informações, consulte a documentação para useActionState.