📚 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:

• API reference
• Routing

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