KEMBAR78
docs: revalidateTag immediate expiration in Route Handlers by icyJoseph · Pull Request #85223 · vercel/next.js · GitHub
Skip to content

Conversation

@icyJoseph
Copy link
Collaborator

Further precision to revalidateTag signature, and escape hatch for route handlers w/ immediate revalidation

@ijjk ijjk added created-by: Next.js DevEx team PRs by the DX team. Documentation Related to Next.js' official documentation. labels Oct 22, 2025
```tsx
revalidateTag(tag: string, profile?: string): void;
```ts
revalidateTag(tag: string, profile?: string | { expire?: number }): void;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The function signature incorrectly marks the profile parameter as optional, but the implementation requires it and shows a deprecation warning when it's missing.

View Details
📝 Patch Details
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

TypeScript signature for revalidateTag incorrectly marks profile parameter as required

What fails: The revalidateTag() function signature in packages/next/src/server/web/spec-extension/revalidate.ts (line 24) requires the profile parameter, but the documentation and runtime behavior indicate it should be optional. This causes TypeScript type errors when calling revalidateTag(tag) without the second argument, even though it's a valid (albeit deprecated) usage pattern.

How to reproduce:

import { revalidateTag } from 'next/cache'

// This matches the documented behavior and runtime behavior,
// but TypeScript complains with error TS2554:
// "Expected 2 arguments, but got 1"
revalidateTag('posts')

// This works without error:
revalidateTag('posts', 'max')

Evidence:

  • Documentation shows signature: revalidateTag(tag: string, profile?: string | { expire?: number }): void - note the ? marker
  • Implementation shows signature: export function revalidateTag(tag: string, profile: string | CacheLifeConfig) - no ? marker
  • Runtime behavior accepts undefined: if (!profile) { console.warn(...) } explicitly handles the missing case
  • Test file at test/e2e/app-dir/app-static/app/update-tag-test/actions.ts contains @ts-expect-error comment before calling revalidateTag('test-update-tag') without second argument, confirming the type mismatch

Result: TypeScript incorrectly enforces that the second argument is required when it should be optional

Expected: The TypeScript function signature should match the documentation and runtime behavior by marking profile as optional with the ? marker: export function revalidateTag(tag: string, profile?: string | CacheLifeConfig)

Fix applied: Added optional marker ? to the profile parameter in the function signature at packages/next/src/server/web/spec-extension/revalidate.ts line 24

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for the time being, one can skip the argument, even though it is deprecated

@icyJoseph icyJoseph marked this pull request as ready for review October 22, 2025 13:27
@icyJoseph icyJoseph merged commit 0b95122 into canary Oct 22, 2025
74 checks passed
@icyJoseph icyJoseph deleted the docs/revalidateTag-expire-0 branch October 22, 2025 13:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

created-by: Next.js DevEx team PRs by the DX team. Documentation Related to Next.js' official documentation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants