Unverified Commit c2863c87 authored by Joseph's avatar Joseph Committed by GitHub

Docs/sync with new features 0 (#84861)

Sync w/ isolatedDevBuild and updateTag+revalidatePath/Tag

---------
Co-authored-by: 's avatarRich Haines <hello@richardhaines.dev>
parent 05627514
...@@ -200,7 +200,7 @@ module.exports = { ...@@ -200,7 +200,7 @@ module.exports = {
[Learn more about fetch logging](/docs/app/api-reference/config/next-config-js/logging). [Learn more about fetch logging](/docs/app/api-reference/config/next-config-js/logging).
## Turbopack tracing ### Turbopack tracing
Turbopack tracing is a tool that helps you understand the performance of your application during local development. Turbopack tracing is a tool that helps you understand the performance of your application during local development.
It provides detailed information about the time taken for each module to compile and how they are related. It provides detailed information about the time taken for each module to compile and how they are related.
...@@ -214,22 +214,24 @@ It provides detailed information about the time taken for each module to compile ...@@ -214,22 +214,24 @@ It provides detailed information about the time taken for each module to compile
1. Navigate around your application or make edits to files to reproduce the problem. 1. Navigate around your application or make edits to files to reproduce the problem.
1. Stop the Next.js development server. 1. Stop the Next.js development server.
1. A file called `trace-turbopack` will be available in the `.next` folder. 1. A file called `trace-turbopack` will be available in the `.next/dev` folder.
1. You can interpret the file using `npx next internal trace [path-to-file]`: 1. You can interpret the file using `npx next internal trace [path-to-file]`:
```bash ```bash
npx next internal trace .next/trace-turbopack npx next internal trace .next/dev/trace-turbopack
``` ```
On versions where `trace` is not available, the command was named `turbo-trace-server`: On versions where `trace` is not available, the command was named `turbo-trace-server`:
```bash ```bash
npx next internal turbo-trace-server .next/trace-turbopack npx next internal turbo-trace-server .next/dev/trace-turbopack
``` ```
1. Once the trace server is running you can view the trace at https://trace.nextjs.org/. 1. Once the trace server is running you can view the trace at https://trace.nextjs.org/.
1. By default the trace viewer will aggregate timings, in order to see each individual time you can switch from "Aggregated in order" to "Spans in order" at the top right of the viewer. 1. By default the trace viewer will aggregate timings, in order to see each individual time you can switch from "Aggregated in order" to "Spans in order" at the top right of the viewer.
## Still having problems? > **Good to know**: The trace file is place under the development server directory, which defaults to `.next/dev`. This is controllable using the [`isolatedDevBuild`](/docs/app/api-reference/config/next-config-js/isolatedDevBuild) flag in your Next config file.
### Still having problems?
Share the trace file generated in the [Turbopack Tracing](#turbopack-tracing) section and share it on [GitHub Discussions](https://github.com/vercel/next.js/discussions) or [Discord](https://nextjs.org/discord). Share the trace file generated in the [Turbopack Tracing](#turbopack-tracing) section and share it on [GitHub Discussions](https://github.com/vercel/next.js/discussions) or [Discord](https://nextjs.org/discord).
...@@ -49,12 +49,13 @@ export async function GET() { ...@@ -49,12 +49,13 @@ export async function GET() {
} }
``` ```
## Relationship with `revalidateTag` ## Relationship with `revalidateTag` and `updateTag`
`revalidatePath` and [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) serve different purposes: `revalidatePath`, [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) and [`updateTag`](/docs/app/api-reference/functions/updateTag) serve different purposes:
- **`revalidatePath`**: Invalidates a specific page or layout path - **`revalidatePath`**: Invalidates a specific page or layout path
- **`revalidateTag`**: Invalidates data with specific tags across all pages that use those tags - **`revalidateTag`**: Marks data with specific tags as **stale**. Applies across all pages that use those tags
- **`updateTag`**: Expires data with specific tags. Applies across all pages that use those tags
When you call `revalidatePath`, only the specified path gets fresh data on the next visit. Other pages that use the same data tags will continue to serve cached data until those specific tags are also revalidated: When you call `revalidatePath`, only the specified path gets fresh data on the next visit. Other pages that use the same data tags will continue to serve cached data until those specific tags are also revalidated:
...@@ -75,20 +76,22 @@ After calling `revalidatePath('/blog')`: ...@@ -75,20 +76,22 @@ After calling `revalidatePath('/blog')`:
- **Page A (/blog)**: Shows fresh data (page re-rendered) - **Page A (/blog)**: Shows fresh data (page re-rendered)
- **Page B (/dashboard)**: Still shows stale data (cache tag 'posts' not invalidated) - **Page B (/dashboard)**: Still shows stale data (cache tag 'posts' not invalidated)
Learn about the difference between [`revalidateTag` and `updateTag`](/docs/app/api-reference/functions/updateTag#differences-from-revalidatetag).
### Building revalidation utilities ### Building revalidation utilities
`revalidatePath` and `revalidateTag` are complementary primitives that are often used together in utility functions to ensure comprehensive data consistency across your application: `revalidatePath` and `updateTag` are complementary primitives that are often used together in utility functions to ensure comprehensive data consistency across your application:
```ts ```ts
'use server' 'use server'
import { revalidatePath, revalidateTag } from 'next/cache' import { revalidatePath, updateTag } from 'next/cache'
export async function updatePost() { export async function updatePost() {
await updatePostInDatabase() await updatePostInDatabase()
revalidatePath('/blog') // Refresh the blog page revalidatePath('/blog') // Refresh the blog page
revalidateTag('posts') // Refresh all pages using 'posts' tag updateTag('posts') // Refresh all pages using 'posts' tag
} }
``` ```
......
...@@ -5,6 +5,8 @@ description: API Reference for the revalidateTag function. ...@@ -5,6 +5,8 @@ description: API Reference for the revalidateTag function.
`revalidateTag` allows you to invalidate [cached data](/docs/app/guides/caching) on-demand for a specific cache tag. `revalidateTag` allows you to invalidate [cached data](/docs/app/guides/caching) on-demand for a specific cache tag.
This function is ideal for content where a slight delay in updates is acceptable, such as blog posts, product catalogs, or documentation. Users receive stale content while fresh data loads in the background.
## Usage ## Usage
`revalidateTag` can be called in Server Functions and Route Handlers. `revalidateTag` can be called in Server Functions and Route Handlers.
...@@ -17,7 +19,7 @@ The revalidation behavior depends on whether you provide the second argument: ...@@ -17,7 +19,7 @@ The revalidation behavior depends on whether you provide the second argument:
- **With `profile="max"` (recommended)**: The tag entry is marked as stale, and the next time a resource with that tag is visited, it will use stale-while-revalidate semantics. This means the stale content is served while fresh content is fetched in the background. - **With `profile="max"` (recommended)**: The tag entry is marked as stale, and the next time a resource with that tag is visited, it will use stale-while-revalidate semantics. This means the stale content is served while fresh content is fetched in the background.
- **With a custom cache life profile**: For advanced usage, you can specify any cache life profile that your application has defined, allowing for custom revalidation behaviors tailored to your specific caching requirements. - **With a custom cache life profile**: For advanced usage, you can specify any cache life profile that your application has defined, allowing for custom revalidation behaviors tailored to your specific caching requirements.
- **Without the second argument (deprecated)**: The tag entry is expired immediately, and the next request to that resource will be a blocking revalidate/cache miss. This behavior is now deprecated, and you should either use `profile="max"` or migrate to `updateTag`. - **Without the second argument (deprecated)**: The tag entry is expired immediately, and the next request to that resource will be a blocking revalidate/cache miss. This behavior is now deprecated, and you should either use `profile="max"` or migrate to [`updateTag`](/docs/app/api-reference/functions/updateTag).
> **Good to know**: When using `profile="max"`, `revalidateTag` marks tagged data as stale, but fresh data is only fetched when pages using that tag are next visited. This means calling `revalidateTag` will not immediately trigger many revalidations at once. The invalidation only happens when any page using that tag is next visited. > **Good to know**: When using `profile="max"`, `revalidateTag` marks tagged data as stale, but fresh data is only fetched when pages using that tag are next visited. This means calling `revalidateTag` will not immediately trigger many revalidations at once. The invalidation only happens when any page using that tag is next visited.
...@@ -30,10 +32,24 @@ revalidateTag(tag: string, profile?: string): void; ...@@ -30,10 +32,24 @@ revalidateTag(tag: string, profile?: string): void;
- `tag`: A string representing the cache tag associated with the data you want to revalidate. Must not exceed 256 characters. This value is case-sensitive. - `tag`: A string representing the cache tag associated with the data you want to revalidate. Must not exceed 256 characters. This value is case-sensitive.
- `profile`: A string that specifies the revalidation behavior. The recommended value is `"max"` which provides stale-while-revalidate semantics. For advanced usage, this can be configured to any cache life profile that your application defines. - `profile`: A string that specifies the revalidation behavior. The recommended value is `"max"` which provides stale-while-revalidate semantics. For advanced usage, this can be configured to any cache life profile that your application defines.
You can add tags to `fetch` as follows: Tags must first be assigned to cached data. You can do this in two ways:
- Using the [`next.tags`](/docs/app/guides/caching#fetch-optionsnexttags-and-revalidatetag) option with `fetch` for caching external API requests:
```tsx
fetch(url, { next: { tags: ['posts'] } })
```
- Using [`cacheTag`](/docs/app/api-reference/functions/cacheTag) inside cached functions or components with the `'use cache'` directive:
```tsx ```tsx
fetch(url, { next: { tags: [...] } }); import { cacheTag } from 'next/cache'
async function getData() {
'use cache'
cacheTag('posts')
// ...
}
``` ```
## Returns ## Returns
...@@ -44,7 +60,7 @@ fetch(url, { next: { tags: [...] } }); ...@@ -44,7 +60,7 @@ fetch(url, { next: { tags: [...] } });
`revalidateTag` invalidates data with specific tags across all pages that use those tags, while [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) invalidates specific page or layout paths. `revalidateTag` invalidates data with specific tags across all pages that use those tags, while [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) invalidates specific page or layout paths.
> **Good to know**: These functions serve different purposes and may need to be used together for comprehensive data consistency. For detailed examples and considerations, see [Relationship with revalidateTag](/docs/app/api-reference/functions/revalidatePath#relationship-with-revalidatetag). > **Good to know**: These functions serve different purposes and may need to be used together for comprehensive data consistency. For detailed examples and considerations, see [relationship with revalidateTag and updateTag](/docs/app/api-reference/functions/revalidatePath#relationship-with-revalidatetag-and-updatetag) for more information.
## Examples ## Examples
......
...@@ -3,15 +3,17 @@ title: updateTag ...@@ -3,15 +3,17 @@ title: updateTag
description: API Reference for the updateTag function. description: API Reference for the updateTag function.
--- ---
`updateTag` allows you to update [cached data](/docs/app/guides/caching) on-demand for a specific cache tag from within Server Actions. This function is designed specifically for read-your-own-writes scenarios. `updateTag` allows you to update [cached data](/docs/app/guides/caching) on-demand for a specific cache tag from within [Server Actions](/docs/app/getting-started/updating-data).
This function is designed for **read-your-own-writes** scenarios, where a user makes a change (like creating a post), and the UI immediately shows the change, rather than stale data.
## Usage ## Usage
`updateTag` can **only** be called from within Server Actions. It cannot be used in Route Handlers, Client Components, or any other context. `updateTag` can **only** be called from within [Server Actions](/docs/app/getting-started/updating-data). It cannot be used in Route Handlers, Client Components, or any other context.
If you need to invalidate cache tags in Route Handlers or other contexts, use [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) instead. If you need to invalidate cache tags in Route Handlers or other contexts, use [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) instead.
> **Good to know**: `updateTag` immediately expires the cached data for the specified tag, causing the next request to that resource to be a blocking revalidate/cache miss. This ensures that Server Actions can immediately see their own writes. > **Good to know**: `updateTag` immediately expires the cached data for the specified tag. The next request will wait to fetch fresh data rather than serving stale content from the cache, ensuring users see their changes immediately.
## Parameters ## Parameters
...@@ -21,6 +23,26 @@ updateTag(tag: string): void; ...@@ -21,6 +23,26 @@ updateTag(tag: string): void;
- `tag`: A string representing the cache tag associated with the data you want to update. Must not exceed 256 characters. This value is case-sensitive. - `tag`: A string representing the cache tag associated with the data you want to update. Must not exceed 256 characters. This value is case-sensitive.
Tags must first be assigned to cached data. You can do this in two ways:
- Using the [`next.tags`](/docs/app/guides/caching#fetch-optionsnexttags-and-revalidatetag) option with `fetch` for caching external API requests:
```tsx
fetch(url, { next: { tags: ['posts'] } })
```
- Using [`cacheTag`](/docs/app/api-reference/functions/cacheTag) inside cached functions or components with the `'use cache'` directive:
```tsx
import { cacheTag } from 'next/cache'
async function getData() {
'use cache'
cacheTag('posts')
// ...
}
```
## Returns ## Returns
`updateTag` does not return a value. `updateTag` does not return a value.
...@@ -31,12 +53,12 @@ While both `updateTag` and `revalidateTag` invalidate cached data, they serve di ...@@ -31,12 +53,12 @@ While both `updateTag` and `revalidateTag` invalidate cached data, they serve di
- **`updateTag`**: - **`updateTag`**:
- Can only be used in Server Actions - Can only be used in Server Actions
- Immediately expires the cache entry (blocking revalidate on next visit) - Next request waits for fresh data (no stale content served)
- Designed for read-your-own-writes scenarios - Designed for read-your-own-writes scenarios
- **`revalidateTag`**: - **`revalidateTag`**:
- Can be used in Server Actions and Route Handlers - Can be used in Server Actions and Route Handlers
- With `profile="max"` (recommended): Uses stale-while-revalidate semantics - With `profile="max"` (recommended): Serves cached data while fetching fresh data in the background (stale-while-revalidate)
- With custom profile: Can be configured to any cache life profile for advanced usage - With custom profile: Can be configured to any cache life profile for advanced usage
- Without profile: legacy behavior which is equivalent to `updateTag` - Without profile: legacy behavior which is equivalent to `updateTag`
...@@ -59,11 +81,13 @@ export async function createPost(formData: FormData) { ...@@ -59,11 +81,13 @@ export async function createPost(formData: FormData) {
data: { title, content }, data: { title, content },
}) })
// Update the cache so the new post is immediately visible // Invalidate cache tags so the new post is immediately visible
// 'posts' tag: affects any page that displays a list of posts
updateTag('posts') updateTag('posts')
// 'post-{id}' tag: affects the individual post detail page
updateTag(`post-${post.id}`) updateTag(`post-${post.id}`)
// Redirect to the new post // Redirect to the new post - user will see fresh data, not cached
redirect(`/posts/${post.id}`) redirect(`/posts/${post.id}`)
} }
``` ```
...@@ -83,11 +107,13 @@ export async function createPost(formData) { ...@@ -83,11 +107,13 @@ export async function createPost(formData) {
data: { title, content }, data: { title, content },
}) })
// Update the cache so the new post is immediately visible // Invalidate cache tags so the new post is immediately visible
// 'posts' tag: affects any page that displays a list of posts
updateTag('posts') updateTag('posts')
// 'post-{id}' tag: affects the individual post detail page
updateTag(`post-${post.id}`) updateTag(`post-${post.id}`)
// Redirect to the new post // Redirect to the new post - user will see fresh data, not cached
redirect(`/posts/${post.id}`) redirect(`/posts/${post.id}`)
} }
``` ```
...@@ -98,11 +124,11 @@ export async function createPost(formData) { ...@@ -98,11 +124,11 @@ export async function createPost(formData) {
import { updateTag } from 'next/cache' import { updateTag } from 'next/cache'
export async function POST() { export async function POST() {
// ❌ This will throw an error // This will throw an error
updateTag('posts') updateTag('posts')
// Error: updateTag can only be called from within a Server Action // Error: updateTag can only be called from within a Server Action
// ✅ Use revalidateTag instead in Route Handlers // Use revalidateTag instead in Route Handlers
revalidateTag('posts', 'max') revalidateTag('posts', 'max')
} }
``` ```
......
...@@ -224,7 +224,9 @@ If you encounter performance or memory issues and want to help the Next.js team ...@@ -224,7 +224,9 @@ If you encounter performance or memory issues and want to help the Next.js team
NEXT_TURBOPACK_TRACING=1 next dev NEXT_TURBOPACK_TRACING=1 next dev
``` ```
This will produce a `.next/trace-turbopack` file. Include that file when creating a GitHub issue on the [Next.js repo](https://github.com/vercel/next.js) to help us investigate. This will produce a `.next/dev/trace-turbopack` file. Include that file when creating a GitHub issue on the [Next.js repo](https://github.com/vercel/next.js) to help us investigate.
By default the development server outputs to `.next/dev`. Read more about [isolatedDevBuild](/docs/app/api-reference/config/next-config-js/isolatedDevBuild).
## Summary ## Summary
...@@ -232,9 +234,9 @@ Turbopack is a **Rust-based**, **incremental** bundler designed to make local de ...@@ -232,9 +234,9 @@ Turbopack is a **Rust-based**, **incremental** bundler designed to make local de
## Version Changes ## Version Changes
| Version | Changes | | Version | Changes |
| --------- | ----------------------------------------------------------------------------------------------------------------- | | --------- | ------------------------------------------------------------------------------------------------------------------ |
| `v16.0.0` | Turbopack becomes the default bundler for Next.js. Automatic support for Babel when a configuration file is found | | `v16.0.0` | Turbopack becomes the default bundler for Next.js. Automatic support for Babel when a configuration file is found. |
| `v15.5.0` | Turbopack support for `build` beta | | `v15.5.0` | Turbopack support for `build` beta |
| `v15.3.0` | Experimental support for `build` | | `v15.3.0` | Experimental support for `build` |
| `v15.0.0` | Turbopack for `dev` stable | | `v15.0.0` | Turbopack for `dev` stable |
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