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	efb383a
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6952f5da6be7d10008546f58
😎 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!

[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.

[ArmandPhilippot]

Thanks for the update! Sorry for these back-and-forths, but rereading this and looking at Vercel's docs, I wonder if, now, this is not even more confusing than your initial caution. We might need to split this information in different places.

I left a suggestion for the "Time-based invalidation" section to avoid repeating what we already describe in the parent section. But, if this doesn't sound enough to you, maybe l258 can be updated with something like:

-By default, an ISR function caches for the duration of your deployment. You can further control caching by setting an expiration time, or by excluding particular routes from caching entirely.
+By default, an ISR function caches for the duration of your deployment. This means Vercel will ignore any custom `Cache-Control` headers. You can further control caching by setting an expiration time, by creating a bypass token, or by excluding particular routes from caching entirely.

This way, I think we don't need asides or to repeat the same information in different places.

I left another suggestion for the "Draft mode" section which is a bit short. I think describing how this is different from the "On-demand invalidation" section could be useful.

After that, I think we'll be in good shape to merge this!

[psd-coder]

Hi! I like the suggestion for the Draft mode section (applied it!), but I’m not sure about other changes. The problem is that you might not need time based expiration at all. You can rely on on-demand invalidation for the most of the pages, but sometimes you require custom cache behavior. In this case you will specify Cache-Control header with necessary directives. And it won’t work… It isn’t really obvious you have to specify some value for expiration to make Cache-Control header work with on-demand invalidation. My goal was to highlight this in the docs. I simplified copy for the Time-based invalidation section. Does it sound better?

"This means cached ISR pages can only be invalidated through on-demand invalidation.": this doesn't sound accurate. They can be invalidated either with bypassToken or expiration. And if we update the sentence, then we're repeating what we say in the parent section.

If I understand everything right, bypassToken doesn't invalidate cache. It just allows you bypass cached value, run function and get fresh page content. It's described here: https://vercel.com/docs/draft-mode

[ArmandPhilippot]

Thanks, I think we're making progress! 😄

Reading Differences between ISR and Cache-Control headers in their docs, I think it would be helpful to link there if we're now talking about Cache Control headers. And, if I understood that correctly, I think these headers are ignored because of Vercel's "cache shielding". So it may be useful to say that instead of the parentheses.

If I understand everything right, bypassToken doesn't invalidate cache. It just allows you bypass cached value, run function and get fresh page content. It's described here: https://vercel.com/docs/draft-mode

Right, on this page, they don't talk about invalidation. But, bypassToken is not only used with Draft mode but also with Prerender Functions. And, on the following page https://vercel.com/docs/build-output-api/features#on-demand-incremental-static-regeneration-isr it seems bypassToken is used "to invalidate the cache at any time" with Prerender Functions.

And this is also the wording you've added under "On-demand invalidation". So thankfully, we don't need to change that and "invalidate" seems the proper wording!

[psd-coder]

Agree, both suggestions are good and give you more context. I applied them. Thanks for your help!

[ArmandPhilippot]

This seems ready to be merged! Thank you for your patience, and welcome to Team Docs! 🎉