📚 Subject area/topic
API Reference
📋 Page(s) affected (or suggested, for new content)
https://docs.astro.build/en/reference/api-reference/#astroredirect
📋 Description of content that is out-of-date or incorrect
Until now (see withastro/astro#11544), the inline documentation for Astro.redirect was misleading: this method is not SSR only. It can also be used with static output but there are some differences. So I suggest to improve the documentation with some additions.
Currently, Astro.redirect is documented in:
I think it makes more sense to update API reference (and this is the link I put in my issue/PR on astro repository).
Document the function signature
Some other functions in the API reference have a Type below that shows the function signature. I think we should do the same for Astro.redirect:
Type: (path: string, status?: number) => Response
And update the link in the sentence below since the value of ValidRedirectStatus (the real number type) is 300 | 301 | 302 | 303 | 304 | 307 | 308 (a redirection status only):
-Allows you to redirect to another page, and optionally provide an [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) as a second parameter.
+Allows you to redirect to another page, and optionally provide an [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages) as a second parameter.
Clarify differences between SSR and static pages
From my understanding, the second parameter only works with SSR: we cannot use a status code with http-equiv. So, it might be useful to clarify the difference in behavior between output: 'static' and output: 'server'.
In API reference, we could add something like what is described in redirects in Configuration reference:
For statically-generated sites, this will produce a client redirect using a [<meta http-equiv="refresh"> tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#http-equiv) and does not support status codes.
When using SSR, status codes are supported. Astro will serve redirected requests with a status of 302 by default unless another code is specified.
And reword the sentence above the example because of this difference:
-The following example redirects a user to a login page, using the default HTTP response status code 302:
+The following example redirects a user to a login page:
Suggestion with changes
### `Astro.redirect()`
**Type:** `(path: string, status?: number) => Response`
Allows you to redirect to another page, and optionally provide an [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) as a second parameter.
A page (and not a child component) must `return` the result of `Astro.redirect()` for the redirect to occur.
For statically-generated sites, this will produce a client redirect using a [<meta http-equiv="refresh"> tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#http-equiv) and does not support status codes.
When using SSR, status codes are supported. Astro will serve redirected requests with a status of 302 by default unless another code is specified.
The following example redirects a user to a login page:
{/* ... The current example ... */}Probably useless
When using hybrid or static, the status code is applied in dev mode since the dev server does not use http-equiv but Vite to serve the pages. So the users might notice this difference. However, I'm not sure it's worth mentioning.
🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)
No response
📚 Subject area/topic
API Reference
📋 Page(s) affected (or suggested, for new content)
https://docs.astro.build/en/reference/api-reference/#astroredirect
📋 Description of content that is out-of-date or incorrect
Until now (see withastro/astro#11544), the inline documentation for
Astro.redirectwas misleading: this method is not SSR only. It can also be used with static output but there are some differences. So I suggest to improve the documentation with some additions.Currently,
Astro.redirectis documented in:I think it makes more sense to update API reference (and this is the link I put in my issue/PR on
astrorepository).Document the function signature
Some other functions in the API reference have a
Typebelow that shows the function signature. I think we should do the same forAstro.redirect:And update the link in the sentence below since the value of
ValidRedirectStatus(the real number type) is300 | 301 | 302 | 303 | 304 | 307 | 308(a redirection status only):Clarify differences between SSR and static pages
From my understanding, the second parameter only works with SSR: we cannot use a status code with
http-equiv. So, it might be useful to clarify the difference in behavior betweenoutput: 'static'andoutput: 'server'.In API reference, we could add something like what is described in
redirectsin Configuration reference:And reword the sentence above the example because of this difference:
Suggestion with changes
Probably useless
When using
hybridorstatic, the status code is applied in dev mode since the dev server does not usehttp-equivbut Vite to serve the pages. So the users might notice this difference. However, I'm not sure it's worth mentioning.🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)
No response