Unverified Commit 67ac8bfd authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

Getting Started Docs: Add `Mutating Data` page (#74018)

Closes: https://linear.app/vercel/issue/DOC-3906/page-mutating-data

---------
Co-authored-by: 's avatarLee Robinson <me@leerob.io>
parent 827fb90b
---
title: How to mutate data
nav_title: Mutating Data
description: Learn how to mutate data in your Next.js application.
related:
title: API Reference
description: Learn more about the features mentioned in this page by reading the API Reference.
links:
- app/api-reference/functions/revalidatePath
- app/api-reference/functions/revalidateTag
- app/api-reference/functions/redirect
---
You can mutate data in Next.js using React's [Server Functions](https://react.dev/reference/rsc/server-functions). This page will go through how you can [create](#creating-server-functions) and [invoke](#invoking-server-functions) Server Functions.
## Creating Server Functions
A Server Function can be defined by using the [`use server`](https://react.dev/reference/rsc/use-server) directive. You can place the directive at the top of an **asynchronous** function to mark the function as a Server Function, or at the top of a separate file to mark all exports of that file. We recommend using a separate file in most instances.
```ts filename="app/lib/actions.ts" switcher
'use server'
export async function createPost(formData: FormData) {}
export async function deletePost(formData: FormData) {}
```
```js filename="app/lib/actions.js" switcher
'use server'
export async function createPost(formData) {}
export async function deletePost(formData) {}
```
### Server Components
Server Functions can be inlined in Server Components by adding the `"use server"` directive to the top of the function body:
```tsx filename="app/page.tsx" switcher
export async default function Page() {
// Server Action
async function createPost() {
'use server'
// Mutate data
// ...
return <></>
}
```
```jsx filename="app/page.js" switcher
export default function Page() {
// Server Action
async function createPost() {
'use server'
// Mutate data
// ...
}
return <></>
}
```
### Client Components
It's not possible to define Server Functions in Client Components. However, you can invoke them in Client Components by importing them from a file that has the `"use server"` directive at the top of it:
```tsx filename="app/actions.ts" switcher
'use server'
export async function createPost() {}
```
```js filename="app/actions.js" switcher
'use server'
export async function createPost() {}
```
```tsx filename="app/ui/button.tsx" switcher
'use client'
import { createPost } from '@/app/actions'
export function Button() {
return <button formAction={createPost}>Create</button>
}
```
```jsx filename="app/ui/button.js" switcher
'use client'
import { createPost } from '@/app/actions'
export function Button() {
return <button formAction={createPost}>Create</button>
}
```
## Invoking Server Functions
There are two mains ways you can invoke a Server Function:
1. [Forms](#forms) in Server and Client Components
2. [Event Handlers](#event-handlers) in Client Components
### Forms
React extends the HTML [`<form>`](https://react.dev/reference/react-dom/components/form) element to allow Server Function to be invoked with the HTML `action` prop.
When invoked in a form, the function automatically receives the [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData/FormData) object. You can extract the data using the native [`FormData` methods](https://developer.mozilla.org/en-US/docs/Web/API/FormData#instance_methods):
```tsx filename="app/ui/form.tsx" switcher
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>
)
}
```
```jsx filename="app/ui/form.js" switcher
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>
)
}
```
```tsx filename="app/actions.ts" switcher
'use server'
export async function createPost(formData: FormData) {
const title = formData.get('title')
const content = formData.get('content')
// Mutate data
// Revalidate cache
}
```
```jsx filename="app/actions.js" switcher
'use server'
export async function createPost(formData) {
const title = formData.get('title')
const content = formData.get('content')
// Mutate data
// Revalidate cache
}
```
> **Good to know:** When passed to the `action` prop, Server Functions are also known as _Server Actions_.
### Event Handlers
You can invoke a Server Function in a Client Component by using event handlers such as `onClick`.
```tsx filename="app/like-button.tsx" switcher
'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>
```
```jsx filename="app/like-button.js" switcher
'use client'
import { incrementLike } from './actions'
import { useState } from 'react'
export default function LikeButton({ initialLikes }) {
const [likes, setLikes] = useState(initialLikes)
return (
<>
<p>Total Likes: {likes}</p>
<button
onClick={async () => {
const updatedLikes = await incrementLike()
setLikes(updatedLikes)
}}
>
Like
</button>
</>
)
}
```
### Showing a pending state
While executing a Server Function, you can show a loading indicator with React's [`useActionState`](https://react.dev/reference/react/useActionState) hook. This hook returns a `pending` boolean:
```tsx filename="app/ui/button.tsx" switcher
'use client'
import { useActionState } 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={async () => action()}>
{pending ? <LoadingSpinner /> : 'Create Post'}
</button>
)
}
```
```jsx filename="app/ui/button.js" switcher
'use client'
import { useActionState } 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={async () => action()}>
{pending ? <LoadingSpinner /> : 'Create Post'}
</button>
)
}
```
### Revalidating the cache
After performing a mutation, you can revalidate the Next.js cache and show the updated data by calling [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) or [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) within the Server Function:
```ts filename="app/lib/actions.ts" switcher
'use server'
import { revalidatePath } from 'next/cache'
export async function createPost(formData: FormData) {
// Mutate data
// ...
revalidatePath('/posts')
}
```
```js filename="app/actions.js" switcher
'use server'
import { revalidatePath } from 'next/cache'
export async function createPost(formData) {
// Mutate data
// ...
revalidatePath('/posts')
}
```
### Redirecting
You may want to redirect the user to a different page after performing a mutation. You can do this by calling [`redirect`](/docs/app/api-reference/functions/redirect) within the Server Function:
```ts filename="app/lib/actions.ts" switcher
'use server'
import { redirect } from 'next/navigation'
export async function createPost(formData: FormData) {
// Mutate data
// ...
redirect('/posts')
}
```
```js filename="app/actions.js" switcher
'use server'
import { redirect } from 'next/navigation'
export async function createPost(formData) {
// Mutate data
// ...
redirect('/posts')
}
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment