Docs/sync with new features 0 (#84861)

icyJoseph · molebox · web-flow · commit c2863c87249b · 2025-10-16T19:31:24.000Z
Sync w/ isolatedDevBuild and updateTag+revalidatePath/Tag

---------

Co-authored-by: Rich Haines &lt;hello@richardhaines.dev&gt;
diff --git a/docs/01-app/02-guides/local-development.mdx b/docs/01-app/02-guides/local-development.mdx
@@ -200,7 +200,7 @@ module.exports = {
 
 [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.
 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
 
 1. Navigate around your application or make edits to files to reproduce the problem.
 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]`:
 
    ```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`:
 
    ```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. 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).
diff --git a/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx b/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx
@@ -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
-- **`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:
 
@@ -75,20 +76,22 @@ After calling `revalidatePath('/blog')`:
 - **Page A (/blog)**: Shows fresh data (page re-rendered)
 - **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
 
-`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
 'use server'
 
-import { revalidatePath, revalidateTag } from 'next/cache'
+import { revalidatePath, updateTag } from 'next/cache'
 
 export async function updatePost() {
   await updatePostInDatabase()
 
   revalidatePath('/blog') // Refresh the blog page
-  revalidateTag('posts') // Refresh all pages using 'posts' tag
+  updateTag('posts') // Refresh all pages using 'posts' tag
 }
 ```
 
diff --git a/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx b/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx
@@ -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.
 
+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
 
 `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:
 
 - **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.
-- **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.
 
@@ -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.
 - `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
-fetch(url, { next: { tags: [...] } });
+import { cacheTag } from 'next/cache'
+
+async function getData() {
+  'use cache'
+  cacheTag('posts')
+  // ...
+}
 ```
 
 ## Returns
@@ -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.
 
-> **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
 
diff --git a/docs/01-app/03-api-reference/04-functions/updateTag.mdx b/docs/01-app/03-api-reference/04-functions/updateTag.mdx
@@ -3,15 +3,17 @@ title: updateTag
 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
 
-`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.
 
-> **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
 
@@ -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.
 
+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
 
 `updateTag` does not return a value.
@@ -31,12 +53,12 @@ While both `updateTag` and `revalidateTag` invalidate cached data, they serve di
 
 - **`updateTag`**:
   - 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
 
 - **`revalidateTag`**:
   - 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
   - Without profile: legacy behavior which is equivalent to `updateTag`
 
@@ -59,11 +81,13 @@ export async function createPost(formData: FormData) {
     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')
+  // 'post-{id}' tag: affects the individual post detail page
   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}`)
 }
 ```
@@ -83,11 +107,13 @@ export async function createPost(formData) {
     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')
+  // 'post-{id}' tag: affects the individual post detail page
   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}`)
 }
 ```
@@ -98,11 +124,11 @@ export async function createPost(formData) {
 import { updateTag } from 'next/cache'
 
 export async function POST() {
-  // ❌ This will throw an error
+  // This will throw an error
   updateTag('posts')
   // 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')
 }
 ```
diff --git a/docs/01-app/03-api-reference/08-turbopack.mdx b/docs/01-app/03-api-reference/08-turbopack.mdx
@@ -224,17 +224,19 @@ If you encounter performance or memory issues and want to help the Next.js team
 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
 
 Turbopack is a **Rust-based**, **incremental** bundler designed to make local development and builds fast—especially for large applications. It is integrated into Next.js, offering zero-config CSS, React, and TypeScript support.
 
 ## 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 |
-| `v15.5.0` | Turbopack support for `build` beta                                                                                |
-| `v15.3.0` | Experimental support for `build`                                                                                  |
-| `v15.0.0` | Turbopack for `dev` stable                                                                                        |
+| Version   | Changes                                                                                                            |
+| --------- | ------------------------------------------------------------------------------------------------------------------ |
+| `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.3.0` | Experimental support for `build`                                                                                   |
+| `v15.0.0` | Turbopack for `dev` stable                                                                                         |
