diff --git a/docs/01-app/01-getting-started/08-updating-data.mdx b/docs/01-app/01-getting-started/08-updating-data.mdx index 30548c96c2d1f1..9932711191c0df 100644 --- a/docs/01-app/01-getting-started/08-updating-data.mdx +++ b/docs/01-app/01-getting-started/08-updating-data.mdx @@ -1,6 +1,6 @@ --- title: Updating Data -description: Learn how to mutate data using Server Functions. +description: Learn how to mutate data using Server Functions and Server Actions in Next.js. related: title: API Reference description: Learn more about the features mentioned in this page by reading the API Reference. @@ -18,6 +18,8 @@ A **Server Function** is an asynchronous function that runs on the server. They In an `action` or mutation context, they are also called **Server Actions**. +> **Good to know:** Server Functions were called "Server Actions". The naming has been updated to reflect that Server Functions can be used for multiple purposes. When you see older tutorials referring to "Server Actions", they're talking about Server Functions. + By convention, a Server Action is an async function used with [`startTransition`](https://react.dev/reference/react/startTransition). This happens automatically when the function is: - Passed to a `
` using the `action` prop. @@ -427,7 +429,7 @@ Calling `redirect` [throws](/docs/app/api-reference/functions/redirect#behavior) You can `get`, `set`, and `delete` cookies inside a Server Action using the [`cookies`](/docs/app/api-reference/functions/cookies) API. -When you [set or delete](/docs/app/api-reference/functions/cookies#understanding-cookie-behavior-in-server-actions) a cookie in a Server Action, Next.js re-renders the current page and its layouts on the server so the **UI reflects the new cookie value**. +When you [set or delete](/docs/app/api-reference/functions/cookies#understanding-cookie-behavior-in-server-functions) a cookie in a Server Action, Next.js re-renders the current page and its layouts on the server so the **UI reflects the new cookie value**. > **Good to know**: The server update applies to the current React tree, re-rendering, mounting, or unmounting components, as needed. Client state is preserved for re-rendered components, and effects re-run if their dependencies changed. diff --git a/docs/01-app/02-guides/redirecting.mdx b/docs/01-app/02-guides/redirecting.mdx index a2e2b326e5b9bf..2fd83f7ac5451b 100644 --- a/docs/01-app/02-guides/redirecting.mdx +++ b/docs/01-app/02-guides/redirecting.mdx @@ -14,13 +14,13 @@ There are a few ways you can handle redirects in Next.js. This page will go thro -| API | Purpose | Where | Status Code | -| ------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | -------------------------------------- | -| [`redirect`](#redirect-function) | Redirect user after a mutation or event | Server Components, Server Actions, Route Handlers | 307 (Temporary) or 303 (Server Action) | -| [`permanentRedirect`](#permanentredirect-function) | Redirect user after a mutation or event | Server Components, Server Actions, Route Handlers | 308 (Permanent) | -| [`useRouter`](#userouter-hook) | Perform a client-side navigation | Event Handlers in Client Components | N/A | -| [`redirects` in `next.config.js`](#redirects-in-nextconfigjs) | Redirect an incoming request based on a path | `next.config.js` file | 307 (Temporary) or 308 (Permanent) | -| [`NextResponse.redirect`](#nextresponseredirect-in-proxy) | Redirect an incoming request based on a condition | Proxy | Any | +| API | Purpose | Where | Status Code | +| ------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------- | -------------------------------------- | +| [`redirect`](#redirect-function) | Redirect user after a mutation or event | Server Components, Server Functions, Route Handlers | 307 (Temporary) or 303 (Server Action) | +| [`permanentRedirect`](#permanentredirect-function) | Redirect user after a mutation or event | Server Components, Server Functions, Route Handlers | 308 (Permanent) | +| [`useRouter`](#userouter-hook) | Perform a client-side navigation | Event Handlers in Client Components | N/A | +| [`redirects` in `next.config.js`](#redirects-in-nextconfigjs) | Redirect an incoming request based on a path | `next.config.js` file | 307 (Temporary) or 308 (Permanent) | +| [`NextResponse.redirect`](#nextresponseredirect-in-proxy) | Redirect an incoming request based on a condition | Proxy | Any | @@ -38,7 +38,7 @@ There are a few ways you can handle redirects in Next.js. This page will go thro ## `redirect` function -The `redirect` function allows you to redirect the user to another URL. You can call `redirect` in [Server Components](/docs/app/getting-started/server-and-client-components), [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Server Actions](/docs/app/getting-started/updating-data). +The `redirect` function allows you to redirect the user to another URL. You can call `redirect` in [Server Components](/docs/app/getting-started/server-and-client-components), [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Server Functions](/docs/app/getting-started/updating-data). `redirect` is often used after a mutation or event. For example, creating a post: @@ -90,7 +90,7 @@ See the [`redirect` API reference](/docs/app/api-reference/functions/redirect) f ## `permanentRedirect` function -The `permanentRedirect` function allows you to **permanently** redirect the user to another URL. You can call `permanentRedirect` in [Server Components](/docs/app/getting-started/server-and-client-components), [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Server Actions](/docs/app/getting-started/updating-data). +The `permanentRedirect` function allows you to **permanently** redirect the user to another URL. You can call `permanentRedirect` in [Server Components](/docs/app/getting-started/server-and-client-components), [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Server Functions](/docs/app/getting-started/updating-data). `permanentRedirect` is often used after a mutation or event that changes an entity's canonical URL, such as updating a user's profile URL after they change their username: diff --git a/docs/01-app/03-api-reference/04-functions/after.mdx b/docs/01-app/03-api-reference/04-functions/after.mdx index 6ff8ec63c58c46..3a7d179358d63b 100644 --- a/docs/01-app/03-api-reference/04-functions/after.mdx +++ b/docs/01-app/03-api-reference/04-functions/after.mdx @@ -5,7 +5,7 @@ description: API Reference for the after function. `after` allows you to schedule work to be executed after a response (or prerender) is finished. This is useful for tasks and other side effects that should not block the response, such as logging and analytics. -It can be used in [Server Components](/docs/app/getting-started/server-and-client-components) (including [`generateMetadata`](/docs/app/api-reference/functions/generate-metadata)), [Server Actions](/docs/app/getting-started/updating-data), [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Proxy](/docs/app/api-reference/file-conventions/proxy). +It can be used in [Server Components](/docs/app/getting-started/server-and-client-components) (including [`generateMetadata`](/docs/app/api-reference/functions/generate-metadata)), [Server Functions](/docs/app/getting-started/updating-data), [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Proxy](/docs/app/api-reference/file-conventions/proxy). The function accepts a callback that will be executed after the response (or prerender) is finished: @@ -59,7 +59,7 @@ export default function Layout({ children }) { ### With request APIs -You can use request APIs such as [`cookies`](/docs/app/api-reference/functions/cookies) and [`headers`](/docs/app/api-reference/functions/headers) inside `after` in [Server Actions](/docs/app/getting-started/updating-data) and [Route Handlers](/docs/app/api-reference/file-conventions/route). This is useful for logging activity after a mutation. For example: +You can use request APIs such as [`cookies`](/docs/app/api-reference/functions/cookies) and [`headers`](/docs/app/api-reference/functions/headers) inside `after` in [Server Functions](/docs/app/getting-started/updating-data) and [Route Handlers](/docs/app/api-reference/file-conventions/route). This is useful for logging activity after a mutation. For example: ```ts filename="app/api/route.ts" highlight={2,7-9} switcher import { after } from 'next/server' diff --git a/docs/01-app/03-api-reference/04-functions/cookies.mdx b/docs/01-app/03-api-reference/04-functions/cookies.mdx index 46066d44274fcf..587bc55237f182 100644 --- a/docs/01-app/03-api-reference/04-functions/cookies.mdx +++ b/docs/01-app/03-api-reference/04-functions/cookies.mdx @@ -3,7 +3,7 @@ title: cookies description: API Reference for the cookies function. --- -`cookies` is an **async** function that allows you to read the HTTP incoming request cookies in [Server Components](/docs/app/getting-started/server-and-client-components), and read/write outgoing request cookies in [Server Actions](/docs/app/getting-started/updating-data) or [Route Handlers](/docs/app/api-reference/file-conventions/route). +`cookies` is an **async** function that allows you to read the HTTP incoming request cookies in [Server Components](/docs/app/getting-started/server-and-client-components), and read/write outgoing request cookies in [Server Functions](/docs/app/getting-started/updating-data) or [Route Handlers](/docs/app/api-reference/file-conventions/route). ```tsx filename="app/page.tsx" switcher import { cookies } from 'next/headers' @@ -68,26 +68,26 @@ To learn more about these options, see the [MDN docs](https://developer.mozilla. - In version 14 and earlier, `cookies` was a synchronous function. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future. - `cookies` is a [Dynamic API](/docs/app/guides/caching#dynamic-rendering) whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into [dynamic rendering](/docs/app/guides/caching#dynamic-rendering). - The `.delete` method can only be called: - - In a [Server Action](/docs/app/getting-started/updating-data) or [Route Handler](/docs/app/api-reference/file-conventions/route). + - In a [Server Function](/docs/app/getting-started/updating-data) or [Route Handler](/docs/app/api-reference/file-conventions/route). - If it belongs to the same domain from which `.set` is called. For wildcard domains, the specific subdomain must be an exact match. Additionally, the code must be executed on the same protocol (HTTP or HTTPS) as the cookie you want to delete. -- HTTP does not allow setting cookies after streaming starts, so you must use `.set` in a [Server Action](/docs/app/getting-started/updating-data) or [Route Handler](/docs/app/api-reference/file-conventions/route). +- HTTP does not allow setting cookies after streaming starts, so you must use `.set` in a [Server Function](/docs/app/getting-started/updating-data) or [Route Handler](/docs/app/api-reference/file-conventions/route). ## Understanding Cookie Behavior in Server Components When working with cookies in Server Components, it's important to understand that cookies are fundamentally a client-side storage mechanism: - **Reading cookies** works in Server Components because you're accessing the cookie data that the client's browser sends to the server in the HTTP request headers. -- **Setting cookies** cannot be done directly in a Server Component, even when using a Route Handler or Server Action. This is because cookies are actually stored by the browser, not the server. +- **Setting cookies** is not supported during Server Component rendering. To modify cookies, invoke a Server Function from the client or use a Route Handler. -The server can only send instructions (via `Set-Cookie` headers) to tell the browser to store cookies - the actual storage happens on the client side. This is why cookie operations that modify state (`.set`, `.delete`) must be performed in a Route Handler or Server Action where the response headers can be properly set. +The server can only send instructions (via `Set-Cookie` headers) to tell the browser to store cookies - the actual storage happens on the client side. This is why cookie operations that modify state (`.set`, `.delete`) must be performed in a Server Function or Route Handler where the response headers can be properly set. -## Understanding Cookie Behavior in Server Actions +## Understanding Cookie Behavior in Server Functions -After you set or delete a cookie in a Server Action, Next.js re-renders the current page and its layouts on the server so the UI reflects the new cookie value. See the [Caching guide](/docs/app/guides/caching#cookies). +After you set or delete a cookie in a Server Function, Next.js can return both the updated UI and new data in a single server roundtrip when the function is used as a [Server Action](/docs/app/getting-started/updating-data#what-are-server-functions) (e.g., passed to a form's `action` prop). See the [Caching guide](/docs/app/guides/caching#cookies). The UI is not unmounted, but effects that depend on data coming from the server will re-run. -To refresh cached data too, call [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) or [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) inside the action. +To refresh cached data too, call [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) or [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) inside the function. ## Examples @@ -149,7 +149,7 @@ export default async function Page() { ### Setting a cookie -You can use the `(await cookies()).set(name, value, options)` method in a [Server Action](/docs/app/getting-started/updating-data) or [Route Handler](/docs/app/api-reference/file-conventions/route) to set a cookie. The [`options` object](#options) is optional. +You can use the `(await cookies()).set(name, value, options)` method in a [Server Function](/docs/app/getting-started/updating-data) or [Route Handler](/docs/app/api-reference/file-conventions/route) to set a cookie. The [`options` object](#options) is optional. ```tsx filename="app/actions.ts" switcher 'use server' diff --git a/docs/01-app/03-api-reference/04-functions/forbidden.mdx b/docs/01-app/03-api-reference/04-functions/forbidden.mdx index 343f4cc5b928a1..1e8f2d6b2e1e4f 100644 --- a/docs/01-app/03-api-reference/04-functions/forbidden.mdx +++ b/docs/01-app/03-api-reference/04-functions/forbidden.mdx @@ -31,7 +31,7 @@ module.exports = { } ``` -`forbidden` can be invoked in [Server Components](/docs/app/getting-started/server-and-client-components), [Server Actions](/docs/app/getting-started/updating-data), and [Route Handlers](/docs/app/api-reference/file-conventions/route). +`forbidden` can be invoked in [Server Components](/docs/app/getting-started/server-and-client-components), [Server Functions](/docs/app/getting-started/updating-data), and [Route Handlers](/docs/app/api-reference/file-conventions/route). ```tsx filename="app/auth/page.tsx" switcher import { verifySession } from '@/app/lib/dal' diff --git a/docs/01-app/03-api-reference/04-functions/permanentRedirect.mdx b/docs/01-app/03-api-reference/04-functions/permanentRedirect.mdx index fb29d2434b6c99..eeec41c101da22 100644 --- a/docs/01-app/03-api-reference/04-functions/permanentRedirect.mdx +++ b/docs/01-app/03-api-reference/04-functions/permanentRedirect.mdx @@ -6,7 +6,7 @@ related: - app/api-reference/functions/redirect --- -The `permanentRedirect` function allows you to redirect the user to another URL. `permanentRedirect` can be used in Server Components, Client Components, [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Server Actions](/docs/app/getting-started/updating-data). +The `permanentRedirect` function allows you to redirect the user to another URL. `permanentRedirect` can be used in Server Components, Client Components, [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Server Functions](/docs/app/getting-started/updating-data). When used in a streaming context, this will insert a meta tag to emit the redirect on the client side. When used in a server action, it will serve a 303 HTTP redirect response to the caller. Otherwise, it will serve a 308 (Permanent) HTTP redirect response to the caller. diff --git a/docs/01-app/03-api-reference/04-functions/redirect.mdx b/docs/01-app/03-api-reference/04-functions/redirect.mdx index e161f5b1cc5881..dbd0264111e937 100644 --- a/docs/01-app/03-api-reference/04-functions/redirect.mdx +++ b/docs/01-app/03-api-reference/04-functions/redirect.mdx @@ -6,7 +6,7 @@ related: - app/api-reference/functions/permanentRedirect --- -The `redirect` function allows you to redirect the user to another URL. `redirect` can be used while rendering in [Server and Client Components](/docs/app/getting-started/server-and-client-components), [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Server Actions](/docs/app/getting-started/updating-data). +The `redirect` function allows you to redirect the user to another URL. `redirect` can be used while rendering in [Server and Client Components](/docs/app/getting-started/server-and-client-components), [Route Handlers](/docs/app/api-reference/file-conventions/route), and [Server Functions](/docs/app/getting-started/updating-data). When used in a [streaming context](/docs/app/getting-started/linking-and-navigating#streaming), this will insert a meta tag to emit the redirect on the client side. When used in a server action, it will serve a 303 HTTP redirect response to the caller. Otherwise, it will serve a 307 HTTP redirect response to the caller. diff --git a/docs/01-app/03-api-reference/04-functions/unauthorized.mdx b/docs/01-app/03-api-reference/04-functions/unauthorized.mdx index 6018acb9ac61b5..93cbb006b418a7 100644 --- a/docs/01-app/03-api-reference/04-functions/unauthorized.mdx +++ b/docs/01-app/03-api-reference/04-functions/unauthorized.mdx @@ -31,7 +31,7 @@ module.exports = { } ``` -`unauthorized` can be invoked in [Server Components](/docs/app/getting-started/server-and-client-components), [Server Actions](/docs/app/getting-started/updating-data), and [Route Handlers](/docs/app/api-reference/file-conventions/route). +`unauthorized` can be invoked in [Server Components](/docs/app/getting-started/server-and-client-components), [Server Functions](/docs/app/getting-started/updating-data), and [Route Handlers](/docs/app/api-reference/file-conventions/route). ```tsx filename="app/dashboard/page.tsx" switcher import { verifySession } from '@/app/lib/dal'