Clarify Vercel adapter ISR caching behavior and reorganize configuration options

[psd-coder]

Description (required)

We have pages with data coming from our CMS, which we invalidate using an on-demand invalidation mechanism, and data coming from third-party APIs, where we want to invalidate the page by setting the necessary s-maxage through Cache-Control header. Occasionally, to make the second approach work, you must specify an expiration value, which isn’t obvious from the docs.

The current docs say ISR “caches for the duration of your deployment,” which is technically accurate, but they don’t warn users that this can make explicit cache headers ineffective. This led to a long debugging process to find the root cause and understand that adding any expiration value restores Cache-Control behavior.

This PR improves the documentation for the ISR feature overall. It:

• Clarifies caching behavior by adding a caution section about Cache-Control behavior when expiration is omitted.
• Restructures the ISR configuration section to better explain different invalidation strategies. (The “Excluding paths from caching” section currently describes three unrelated features together: exclude, bypassToken for on-demand invalidation and bypassToken for draft mode).
• Fixes a typo.

Related issues & labels (optional)

• Suggested label: improve or update documentation

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	ffc7204
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/694c04bbd4e919000869118d
😎 Deploy Preview	https://deploy-preview-12954--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/integrations-guide/vercel.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[ArmandPhilippot]

Hi @psd-coder, I'm taking over because Sarah is on holiday.

Thank you for the update, this looks great! And integrating the text without the caution looks much better.

I left two suggestions:

• the first one is mostly nitpicking and I'll need you to weight on this because I'm not familiar with Vercel. I feel like your new paragraph should be after the heading not before to keep things tied (expiration belongs to the heading talking about expiration) and this can probably be integrated with the current sentence. Does this feel right to you? Do not hesitate to make my suggestion (or rather my quote, due to how GitHub works) accurate!
• and another one to fix a rendering issue. This one should be straightforward!

[ArmandPhilippot]

Any reasons to talk about expiration before the dedicated heading? I'm not familiar with Vercel but reading this, I wonder if this shouldn't be said after the heading and even merged with the current sentence. Something like:

By default or when using false, the pages will stay cached as long as the current deployment is in production. This means cached ISR pages can only be invalidated through on-demand invalidation and any custom Cache-Control headers you set on these pages will be ignored by Vercel's edge cache.

To control caching behavior through Cache-Control headers (for example, to set shorter TTLs on pages with third-party API data), you have to change the length of time to cache routes by configuring an expiration value in seconds:

I can't make a proper suggestion because of the updated line below; GitHub says it can make a suggestion on deleted lines.

[ArmandPhilippot]

This was removed but this break the rendering:

Suggested change

	})
	})
	```

[psd-coder]

Hi @ArmandPhilippot! Your suggestions make sense. I moved the explanation to the end of Time-based invalidation section and fixed the markup issue. I hope it looks better now.