Note static endpoint can return a response object

[bluwy]

What kind of changes does this PR include?

• New or updated content

Description

Based on withastro/astro#5258, clarify that you can return a response object from a static endpoint as long as it's a successful response.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	f111ea7
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/635fd712e66a7900077e7311
😎 Deploy Preview	https://deploy-preview-1961--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 site settings.

[delucis]

I’m wondering if we want to document this? I understand supporting it for consistency, but if I understand correctly you can’t use any of the features of Response really, right? Headers etc. aren’t supported. Are there any circumstances where returning a Response would be preferable to { body: '...' }?

[bluwy]

Yeah there's not much features you can use with Response now other than user preference. I can also see not documenting this and have the Astro errors cover it too, which I'm also fine with! Right now it's here to only document the possibility, but happy to close this if you prefer too.

[delucis]

I’d like another opinion from @Jutanium or @sarah11918 before I stomp on your PR! 😅

But I definitely think it’s OK to merge the Astro feature without this PR merged yet and we can take a bit more time to decide how best to document this.

[Jutanium]

I discovered when first working on this guide that it worked in dev and not build, so thanks @bluwy for fixing that! In terms of docs, I like first introducing the a full-fledged Response in the SSR section, where it fully works. We don't want to imply that statusText or headers work in SSG mode, and introducing it there with those caveats begs the question of why you'd use it at all.

The flip side is that someone might try to use it in SSG mode, notice that it partially works, and then get confused when most of it gets ignored. In the spirit of "don't include code samples that we don't want copied", we could replace the code sample with a note or caution:

:::caution
You can return a Response object, but it must return a successful status code. The response body will be built as the endpoint, but other properties (like header and statusText) will be ignored.
:::

I'm also happy to not include it at all.

[bluwy]

Thanks for the comments @Jutanium. I think it sounds better to not document this until we have better support for it. I agree with all the points you mentioned! Closing this one for now.