mirror of
https://github.com/hanzoai/next.js.git
synced 2026-10-30 14:46:38 +00:00
c2b4c0815c
This PRs unifies the caching story across the docs, making Cache Components the happy path, while still providing guidance to users in the old model. However, instead of explaining the old model and its caching layers, we've created a new guide focusing on what APIs to use and when. This follow-up PR aligns terminology across the docs: https://github.com/vercel/next.js/pull/90589 ## IA updates Getting Started section: - Improves Getting Started progression: - **Before:** CC → Fetching Data → Updating Data → Caching and Revalidating (old and new model mixed) - **After:** Fetching Data (Dynamic) → Mutating Data (Dynamic) → Caching with CC (Prerendering) → Revalidating with CC. - New: `caching.mdx` (CC-first) - Structure: - Enabling Cache Components - Data vs UI-level caching - Working with request time APIs - Passing request values to cached functions - Working with non-deterministic operations - Working with synchronous operations - How rendering works (PPR and static shell story) - New: `revalidating.mdx` (CC-first) - Explains how to use `cacheLife` and `cacheTag` Guides Section: - New: `caching-and-revalidating.mdx` (Previous Model) - For users who are not using CC, includes `fetch` options and route segment config - Moves route segment config options that don't apply to CC from API reference to this guide (for easy archiving in the future). - New: `migrating-to-cache-components.mdx` (WIP) - Del: `caching.mdx` 😌 ## Terminology We should remove caching layers from the docs. Users only needed to be exposed to them when they were configured independently, but the new CC APIs work across layers. To make it easier to review this PR, I'm consolidating terminology and fixing broken links in a new PR: https://github.com/vercel/next.js/pull/90589 --------- Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: Joseph <[email protected]>
173 lines
4.4 KiB
Plaintext
173 lines
4.4 KiB
Plaintext
---
|
|
title: forbidden
|
|
description: API Reference for the forbidden function.
|
|
version: experimental
|
|
related:
|
|
links:
|
|
- app/api-reference/file-conventions/forbidden
|
|
---
|
|
|
|
The `forbidden` function throws an error that renders a Next.js 403 error page. It's useful for handling authorization errors in your application. You can customize the UI using the [`forbidden.js` file](/docs/app/api-reference/file-conventions/forbidden).
|
|
|
|
To start using `forbidden`, enable the experimental [`authInterrupts`](/docs/app/api-reference/config/next-config-js/authInterrupts) configuration option in your `next.config.js` file:
|
|
|
|
```ts filename="next.config.ts" switcher
|
|
import type { NextConfig } from 'next'
|
|
|
|
const nextConfig: NextConfig = {
|
|
experimental: {
|
|
authInterrupts: true,
|
|
},
|
|
}
|
|
|
|
export default nextConfig
|
|
```
|
|
|
|
```js filename="next.config.js" switcher
|
|
module.exports = {
|
|
experimental: {
|
|
authInterrupts: true,
|
|
},
|
|
}
|
|
```
|
|
|
|
`forbidden` can be invoked in [Server Components](/docs/app/getting-started/server-and-client-components), [Server Functions](/docs/app/getting-started/mutating-data), and [Route Handlers](/docs/app/api-reference/file-conventions/route).
|
|
|
|
```tsx filename="app/auth/page.tsx" switcher
|
|
import { verifySession } from '@/app/lib/dal'
|
|
import { forbidden } from 'next/navigation'
|
|
|
|
export default async function AdminPage() {
|
|
const session = await verifySession()
|
|
|
|
// Check if the user has the 'admin' role
|
|
if (session.role !== 'admin') {
|
|
forbidden()
|
|
}
|
|
|
|
// Render the admin page for authorized users
|
|
return <></>
|
|
}
|
|
```
|
|
|
|
```jsx filename="app/auth/page.js" switcher
|
|
import { verifySession } from '@/app/lib/dal'
|
|
import { forbidden } from 'next/navigation'
|
|
|
|
export default async function AdminPage() {
|
|
const session = await verifySession()
|
|
|
|
// Check if the user has the 'admin' role
|
|
if (session.role !== 'admin') {
|
|
forbidden()
|
|
}
|
|
|
|
// Render the admin page for authorized users
|
|
return <></>
|
|
}
|
|
```
|
|
|
|
## Good to know
|
|
|
|
- The `forbidden` function cannot be called in the [root layout](/docs/app/api-reference/file-conventions/layout#root-layout).
|
|
|
|
## Examples
|
|
|
|
### Role-based route protection
|
|
|
|
You can use `forbidden` to restrict access to certain routes based on user roles. This ensures that users who are authenticated but lack the required permissions cannot access the route.
|
|
|
|
```tsx filename="app/admin/page.tsx" switcher
|
|
import { verifySession } from '@/app/lib/dal'
|
|
import { forbidden } from 'next/navigation'
|
|
|
|
export default async function AdminPage() {
|
|
const session = await verifySession()
|
|
|
|
// Check if the user has the 'admin' role
|
|
if (session.role !== 'admin') {
|
|
forbidden()
|
|
}
|
|
|
|
// Render the admin page for authorized users
|
|
return (
|
|
<main>
|
|
<h1>Admin Dashboard</h1>
|
|
<p>Welcome, {session.user.name}!</p>
|
|
</main>
|
|
)
|
|
}
|
|
```
|
|
|
|
```jsx filename="app/admin/page.js" switcher
|
|
import { verifySession } from '@/app/lib/dal'
|
|
import { forbidden } from 'next/navigation'
|
|
|
|
export default async function AdminPage() {
|
|
const session = await verifySession()
|
|
|
|
// Check if the user has the 'admin' role
|
|
if (session.role !== 'admin') {
|
|
forbidden()
|
|
}
|
|
|
|
// Render the admin page for authorized users
|
|
return (
|
|
<main>
|
|
<h1>Admin Dashboard</h1>
|
|
<p>Welcome, {session.user.name}!</p>
|
|
</main>
|
|
)
|
|
}
|
|
```
|
|
|
|
### Mutations with Server Actions
|
|
|
|
When implementing mutations in Server Actions, you can use `forbidden` to only allow users with a specific role to update sensitive data.
|
|
|
|
```ts filename="app/actions/update-role.ts" switcher
|
|
'use server'
|
|
|
|
import { verifySession } from '@/app/lib/dal'
|
|
import { forbidden } from 'next/navigation'
|
|
import db from '@/app/lib/db'
|
|
|
|
export async function updateRole(formData: FormData) {
|
|
const session = await verifySession()
|
|
|
|
// Ensure only admins can update roles
|
|
if (session.role !== 'admin') {
|
|
forbidden()
|
|
}
|
|
|
|
// Perform the role update for authorized users
|
|
// ...
|
|
}
|
|
```
|
|
|
|
```js filename="app/actions/update-role.js" switcher
|
|
'use server'
|
|
|
|
import { verifySession } from '@/app/lib/dal'
|
|
import { forbidden } from 'next/navigation'
|
|
import db from '@/app/lib/db'
|
|
|
|
export async function updateRole(formData) {
|
|
const session = await verifySession()
|
|
|
|
// Ensure only admins can update roles
|
|
if (session.role !== 'admin') {
|
|
forbidden()
|
|
}
|
|
|
|
// Perform the role update for authorized users
|
|
// ...
|
|
}
|
|
```
|
|
|
|
## Version History
|
|
|
|
| Version | Changes |
|
|
| --------- | ----------------------- |
|
|
| `v15.1.0` | `forbidden` introduced. |
|