Unverified Commit f0088acc authored by David Alexandru Ilie's avatar David Alexandru Ilie Committed by GitHub

docs: warn when catching permanentRedirect (#97496)

## Summary

Document that `permanentRedirect()` throws and should be called outside
a broad `try/catch` block.

The `redirect()` and `notFound()` references already explain this
control-flow requirement. The `permanentRedirect()` reference omits it,
so application error handling can accidentally suppress the redirect.

Align the page with the `redirect()` reference by adding a dedicated
Behavior section for the try/catch guidance and temporary-redirect
cross-link.

## Verification

- Prettier, ESLint, and `git diff --check`
parent b18acf67
...@@ -12,8 +12,6 @@ When used in a streaming context, this will insert a meta tag to emit the redire ...@@ -12,8 +12,6 @@ When used in a streaming context, this will insert a meta tag to emit the redire
If a resource doesn't exist, you can use the [`notFound` function](/docs/app/api-reference/functions/not-found) instead. If a resource doesn't exist, you can use the [`notFound` function](/docs/app/api-reference/functions/not-found) instead.
> **Good to know**: If you prefer to return a 307 (Temporary) HTTP redirect instead of 308 (Permanent), you can use the [`redirect` function](/docs/app/api-reference/functions/redirect) instead.
## Parameters ## Parameters
The `permanentRedirect` function accepts two arguments: The `permanentRedirect` function accepts two arguments:
...@@ -45,6 +43,11 @@ The `type` parameter has no effect when used in Server Components. ...@@ -45,6 +43,11 @@ The `type` parameter has no effect when used in Server Components.
`permanentRedirect` does not return a value. `permanentRedirect` does not return a value.
## Behavior
- In Server Actions and Route Handlers, `permanentRedirect` should be called **outside** the `try` block when using `try/catch` statements because it throws an error.
- If you prefer to return a 307 (Temporary) HTTP redirect instead of 308 (Permanent), you can use the [`redirect` function](/docs/app/api-reference/functions/redirect) instead.
## Example ## Example
Invoking the `permanentRedirect()` function throws a `NEXT_REDIRECT` error and terminates rendering of the route segment in which it was thrown. Invoking the `permanentRedirect()` function throws a `NEXT_REDIRECT` error and terminates rendering of the route segment in which it was thrown.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment