docs: revalidateTag requires second argument

[icyJoseph]

Closes: #85281

[vercel]

The function signature marks the profile parameter as required, but the documentation text explicitly describes calling revalidateTag without a second argument as deprecated functionality. This is a contradiction.

View Details

📝 Patch Details

diff --git a/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx b/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx
index aedaa553c8..512975a40f 100644
--- a/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx
+++ b/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx
@@ -26,11 +26,11 @@ The revalidation behavior depends on whether you provide the second argument:
 ## Parameters
 
 ```ts
-revalidateTag(tag: string, profile: string | { expire?: number }): void;
+revalidateTag(tag: string, profile?: string | { expire?: number }): 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, or any of the other default or custom profiles defined in [`cacheLife`](/docs/app/api-reference/config/next-config-js/cacheLife). Alternatively, you can pass an object with an `expire` property for custom expiration behavior.
+- `profile` (optional): A string that specifies the revalidation behavior. The recommended value is `"max"` which provides stale-while-revalidate semantics, or any of the other default or custom profiles defined in [`cacheLife`](/docs/app/api-reference/config/next-config-js/cacheLife). Alternatively, you can pass an object with an `expire` property for custom expiration behavior.
 
 Tags must first be assigned to cached data. You can do this in two ways:
 
diff --git a/packages/next/src/server/web/spec-extension/revalidate.ts b/packages/next/src/server/web/spec-extension/revalidate.ts
index da9c2b4bf7..a44cd266ad 100644
--- a/packages/next/src/server/web/spec-extension/revalidate.ts
+++ b/packages/next/src/server/web/spec-extension/revalidate.ts
@@ -21,7 +21,7 @@ type CacheLifeConfig = {
  *
  * Read more: [Next.js Docs: `revalidateTag`](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)
  */
-export function revalidateTag(tag: string, profile: string | CacheLifeConfig) {
+export function revalidateTag(tag: string, profile?: string | CacheLifeConfig) {
   if (!profile) {
     console.warn(
       '"revalidateTag" without the second argument is now deprecated, add second argument of "max" or use "updateTag". See more info here: https://nextjs.org/docs/messages/revalidate-tag-single-arg'

Analysis

Function signature contradicts deprecated functionality in revalidateTag

What fails: The revalidateTag() function signature requires the profile parameter, but the documentation and implementation describe calling without it as deprecated (not removed). TypeScript users cannot call revalidateTag('tag') without a second argument, contradicting the documented deprecated usage pattern.

How to reproduce: Create a TypeScript file with strict type checking:

import { revalidateTag } from 'next/cache'

revalidateTag('posts')  // TypeScript error: Missing argument 'profile'

Expected behavior vs actual: The function signature should match the implementation and documentation. Since the implementation includes if (!profile) to check for missing arguments and logs a deprecation warning, the parameter must be optional (profile?).

Root cause: PR #83822 (October 9, 2025) changed the signature from revalidateTag(tag: string) to revalidateTag(tag: string, profile: string | CacheLifeConfig) without making the profile parameter optional, despite the implementation still supporting the deprecated single-argument call.

Fix: Added optional marker to both the implementation signature and documentation to make profile optional (profile?), aligning with the actual behavior where callers can omit the second argument and receive a deprecation warning.

[saoudi-h]

I think we're fixing the wrong thing here. Instead of changing the docs to match the code, shouldn't we fix the code to match the docs?

Making profile required is a breaking change that forces many developers to update dozens or hundreds of calls. Personally I have 79 revalidateTag() calls, and the original issue mentioned 150.

Most people will just set it to 'max' anyway since it's the recommended value. Can we make profile optional with 'max' as default instead? This would save everyone a lot of unnecessary work.