Pular para o conteúdo
Documentação do Next.js PT-BR

Modificando dados

Você pode modificar dados no Next.js usando React Server Functions. Esta página mostra como criar e invocar Server Functions. Para comportamentos específicos do Next.js (resposta em uma única ida e volta ao servidor, despacho sequencial, segurança, deploy), veja Server Actions e mutações.

O que são Server Functions?

Uma Server Function é uma função assíncrona que roda no servidor. Você pode chamá-la a partir do cliente por meio de uma requisição de rede, por isso ela precisa ser assíncrona.

Em um contexto de action ou mutação, elas também são chamadas de Server Actions.

Por convenção, uma Server Action é uma função assíncrona usada com startTransition. Isso acontece automaticamente quando a função é:

  • Passada para um <form> pela prop action.
  • Passada para um <button> pela prop formAction.

Quando uma action é invocada, o Next.js pode retornar, em uma única ida e volta ao servidor, tanto a UI atualizada quanto os dados novos.

Por baixo dos panos, as actions usam o método POST, e somente esse método HTTP pode invocá-las.

[!WARNING] Server Functions são acessíveis por requisições POST diretas, não apenas pela UI do seu app. Sempre verifique a autenticação e a autorização dentro de cada Server Function. Veja o guia de segurança de dados para os padrões recomendados.

Bom saber: Uma Server Action é uma Server Function usada de um modo específico (para tratar envios de formulário e mutações). Server Function é o termo mais amplo.

Criando Server Functions

Uma Server Function pode ser definida com a diretiva use server. Você pode colocar a diretiva no topo de uma função assíncrona para marcá-la como Server Function, ou no topo de um arquivo separado para marcar todas as exportações desse arquivo.

app/lib/actions.ts
import { auth } from '@/lib/auth'

export async function createPost(formData: FormData) {
  'use server'
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  const title = formData.get('title')
  const content = formData.get('content')

  // Mutate data
  // Revalidate cache
}

export async function deletePost(formData: FormData) {
  'use server'
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  const id = formData.get('id')

  // Verify the user owns this resource before deleting
  // Mutate data
  // Revalidate cache
}

Server Components

Server Functions podem ser definidas inline em Server Components, adicionando a diretiva "use server" no topo do corpo da função:

app/page.tsx
export default function Page() {
  // Server Action
  async function createPost(formData: FormData) {
    'use server'
    // ...
  }

  return <></>
}

Bom saber: Server Components oferecem progressive enhancement por padrão, ou seja, formulários que chamam Server Actions são enviados mesmo que o JavaScript ainda não tenha carregado ou esteja desativado.

Client Components

Não é possível definir Server Functions em Client Components. No entanto, você pode invocá-las em Client Components importando-as de um arquivo que tenha a diretiva "use server" no topo:

app/actions.ts
'use server'

export async function createPost() {}
app/ui/button.tsx
'use client'

import { createPost } from '@/app/actions'

export function Button() {
  return <button formAction={createPost}>Create</button>
}

Bom saber: Em Client Components, formulários que invocam Server Actions colocam os envios na fila caso o JavaScript ainda não tenha carregado, e esses envios são priorizados na hydration. Depois da hydration, o navegador não recarrega a página ao enviar o formulário.

Passando actions como props

Você também pode passar uma action para um Client Component como prop:

<ClientComponent updateItemAction={updateItem} />
app/client-component.tsx
'use client'

export default function ClientComponent({
  updateItemAction,
}: {
  updateItemAction: (formData: FormData) => void
}) {
  return <form action={updateItemAction}>{/* ... */}</form>
}

Invocando Server Functions

Há duas formas principais de invocar uma Server Function:

  1. Formulários em Server e Client Components
  2. Manipuladores de eventos e useEffect em Client Components

Bom saber: Server Functions são projetadas para mutações no servidor. O cliente as despacha e aguarda uma de cada vez. Veja Despacho sequencial no cliente. Se você precisar de busca de dados em paralelo, use busca de dados em Server Components, ou execute trabalho em paralelo dentro de uma única Server Function ou de um Route Handler.

Formulários

O React estende o elemento HTML <form> para permitir que uma Server Function seja invocada pela prop HTML action.

Quando invocada em um formulário, a função recebe automaticamente o objeto FormData. Você pode extrair os dados usando os métodos nativos de FormData:

app/ui/form.tsx
import { createPost } from '@/app/actions'

export function Form() {
  return (
    <form action={createPost}>
      <input type="text" name="title" />
      <input type="text" name="content" />
      <button type="submit">Create</button>
    </form>
  )
}
app/actions.ts
'use server'

import { auth } from '@/lib/auth'

export async function createPost(formData: FormData) {
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  const title = formData.get('title')
  const content = formData.get('content')

  // Mutate data
  // Revalidate cache
}

Manipuladores de eventos

Você pode invocar uma Server Function em um Client Component usando manipuladores de eventos, como onClick.

app/like-button.tsx
'use client'

import { incrementLike } from './actions'
import { useState } from 'react'

export default function LikeButton({ initialLikes }: { initialLikes: number }) {
  const [likes, setLikes] = useState(initialLikes)

  return (
    <>
      <p>Total Likes: {likes}</p>
      <button
        onClick={async () => {
          const updatedLikes = await incrementLike()
          setLikes(updatedLikes)
        }}
      >
        Like
      </button>
    </>
  )
}

Exemplos

Exibindo um estado pendente

Enquanto uma Server Function é executada, você pode mostrar um indicador de carregamento com o hook useActionState do React. Esse hook retorna um booleano pending:

app/ui/button.tsx
'use client'

import { useActionState, startTransition } from 'react'
import { createPost } from '@/app/actions'
import { LoadingSpinner } from '@/app/ui/loading-spinner'

export function Button() {
  const [state, action, pending] = useActionState(createPost, false)

  return (
    <button onClick={() => startTransition(action)}>
      {pending ? <LoadingSpinner /> : 'Create Post'}
    </button>
  )
}

Veja o guia Criando apps interativos para um passo a passo mais detalhado sobre interações responsivas, incluindo feedback de pendência, UI otimista, transições e tratamento de erros.

Bom saber: Com a configuração experimental useOffline ativada, uma Server Action interrompida por uma queda de conexão fica pendente e é concluída quando a rede volta.

Atualizar dados

Depois de uma mutação, talvez você queira atualizar a página atual para mostrar os dados mais recentes. Para isso, chame refresh de next/cache em uma Server Action:

app/lib/actions.ts
'use server'

import { auth } from '@/lib/auth'
import { refresh } from 'next/cache'

export async function updatePost(formData: FormData) {
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }
  // Mutate data
  // ...

  refresh()
}

Isso atualiza o router do cliente, garantindo que a UI reflita o estado mais recente. A função refresh() não revalida dados com tag. Para revalidar dados com tag, use updateTag ou revalidateTag.

Revalidar dados

Depois de executar uma mutação, você pode revalidar o cache do Next.js e mostrar os dados atualizados chamando revalidatePath ou revalidateTag dentro da Server Function:

app/lib/actions.ts
import { auth } from '@/lib/auth'
import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  'use server'
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }
  // Mutate data
  // ...

  revalidatePath('/posts')
}

Redirecionar após uma mutação

Talvez você queira redirecionar o usuário para outra página depois de uma mutação. Para isso, chame redirect dentro da Server Function.

app/lib/actions.ts
'use server'

import { auth } from '@/lib/auth'
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'

export async function createPost(formData: FormData) {
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }
  // Mutate data
  // ...

  revalidatePath('/posts')
  redirect('/posts')
}

Chamar redirect lança uma exceção de controle de fluxo tratada pelo framework. Nenhum código depois dela é executado. Se você precisar de dados atualizados, chame revalidatePath ou revalidateTag antes.

Cookies

Você pode get, set e delete cookies dentro de uma Server Action usando a API cookies.

Quando você define ou remove um cookie em uma Server Action, o Next.js renderiza de novo a página atual e seus layouts no servidor, para que a UI reflita o novo valor do cookie.

Bom saber: A atualização no servidor se aplica à árvore React atual, renderizando de novo, montando ou desmontando componentes conforme necessário. O estado do cliente é preservado nos componentes renderizados de novo, e os effects são executados de novo se as dependências tiverem mudado.

app/actions.ts
'use server'

import { cookies } from 'next/headers'

export async function exampleAction() {
  const cookieStore = await cookies()

  // Get cookie
  cookieStore.get('name')?.value

  // Set cookie
  cookieStore.set('name', 'Delba')

  // Delete cookie
  cookieStore.delete('name')
}

useEffect

Você pode usar o hook useEffect do React para invocar uma Server Action quando o componente é montado ou quando uma dependência muda. Isso é útil para mutações que dependem de eventos globais ou que precisam ser disparadas automaticamente. Por exemplo, onKeyDown para atalhos do app, um hook de intersection observer para rolagem infinita, ou quando o componente é montado para atualizar uma contagem de visualizações:

app/view-count.tsx
'use client'

import { incrementViews } from './actions'
import { useState, useEffect, useTransition } from 'react'

export default function ViewCount({ initialViews }: { initialViews: number }) {
  const [views, setViews] = useState(initialViews)
  const [isPending, startTransition] = useTransition()

  useEffect(() => {
    startTransition(async () => {
      const updatedViews = await incrementViews()
      setViews(updatedViews)
    })
  }, [])

  // You can use `isPending` to give users feedback
  return <p>Total Views: {views}</p>
}

Próximos passos

Saiba mais sobre Server Actions e as APIs mencionadas nesta página.