136 lines
4.9 KiB
Markdown
136 lines
4.9 KiB
Markdown
---
|
|
title: "Payload CMS — Admin Panel Overview"
|
|
aliases: [payload-admin, payloadcms-admin-panel]
|
|
tags: [payloadcms, admin, nextjs, react, cms, auth, i18n]
|
|
sources: [raw/admin__overview.md]
|
|
created: 2026-05-15
|
|
updated: 2026-05-15
|
|
---
|
|
|
|
## What It Is
|
|
|
|
Payload auto-generates a fully type-safe, React/Next.js Admin Panel for managing users and data. Built on the **Next.js App Router** with React Server Components. Supports 100+ fields with no performance degradation; translated into 30+ languages.
|
|
|
|
## Project Structure
|
|
|
|
All Payload routes live inside the `(payload)` route group:
|
|
|
|
```
|
|
app/
|
|
├─ (payload)/
|
|
│ ├─ admin/[[...segments]]/ ← Admin UI pages
|
|
│ ├─ api/[...slug]/ ← REST API
|
|
│ ├─ graphql/ ← GraphQL API
|
|
│ ├─ graphql-playground/
|
|
│ ├─ custom.scss ← Global style overrides
|
|
│ └─ layout.tsx ← Sets html lang/dir attrs
|
|
```
|
|
|
|
- Move `(payload)` anywhere by updating `routes` + `admin.importMap` in config.
|
|
- Delete unwanted directories (admin, api, graphql) to opt out — overhead is fully scoped.
|
|
|
|
## Key Config Options (`admin` key in Payload Config)
|
|
|
|
| Option | Purpose |
|
|
|--------|---------|
|
|
| `user` | Slug of auth-enabled Collection that can log in |
|
|
| `components` | Swap in custom React components globally |
|
|
| `routes` | Override built-in admin route paths |
|
|
| `livePreview` | Real-time front-end preview |
|
|
| `theme` | Lock to `light` or `dark`, default `all` |
|
|
| `timezones` | IANA timezone list + default (display only; DB always UTC) |
|
|
| `toast` | Duration, position, limit of toast notifications |
|
|
| `dateFormat` | Any `date-fns` format string |
|
|
| `meta` | SEO metadata for the panel |
|
|
| `autoLogin` | Dev/demo convenience auto-login |
|
|
|
|
## Auth & User Collection
|
|
|
|
- Only **one** auth-enabled Collection can access the Admin Panel.
|
|
- Default: auto-generated `users` collection. Override by adding your own `slug: 'users'`.
|
|
- Set `admin: { user: 'admins' }` to use a different collection (e.g. separate `admins` vs `customers`).
|
|
|
|
### Role-Based Access Control (RBAC)
|
|
|
|
Add a `roles` field to the auth collection → use `access.admin` to gate panel entry. Multiple roles (e.g. `super-admin`, `editor`) can share the same collection with different permission levels.
|
|
|
|
## Customizing Routes
|
|
|
|
### Root-level Routes
|
|
|
|
```ts
|
|
routes: {
|
|
admin: '/custom-admin-route', // default: /admin
|
|
api: '/api',
|
|
graphQL: '/graphql',
|
|
graphQLPlayground: '/graphql-playground',
|
|
}
|
|
```
|
|
|
|
Changing `routes.admin` requires updating the file system structure to match.
|
|
|
|
### Admin-level Routes
|
|
|
|
```ts
|
|
admin: {
|
|
routes: {
|
|
account: '/my-account', // default: /account
|
|
login: '/login',
|
|
logout: '/logout',
|
|
forgot: '/forgot',
|
|
reset: '/reset',
|
|
unauthorized: '/unauthorized',
|
|
inactivity: '/logout-inactivity',
|
|
createFirstUser: '/create-first-user',
|
|
}
|
|
}
|
|
```
|
|
|
|
## I18n
|
|
|
|
- 30+ languages auto-detected from browser locale.
|
|
- Users can override from their account page.
|
|
- Falls back to English if locale unsupported.
|
|
|
|
## Timezones
|
|
|
|
- Dates **always stored in UTC** in DB; timezone config is display-only.
|
|
- `supportedTimezones`: array of `{label, value}` (IANA names) **or** a function `({ defaultTimezones }) => [...]` to extend defaults.
|
|
- `defaultTimezone`: IANA string, e.g. `America/Los_Angeles`.
|
|
- Must also enable `timezone: true` on individual Date fields.
|
|
- Use `{ label: 'UTC', value: 'UTC' }` to show raw UTC to editors.
|
|
|
|
## Toast Notifications (Sonner library)
|
|
|
|
| Option | Default | Notes |
|
|
|--------|---------|-------|
|
|
| `duration` | 4000ms | Display time per toast |
|
|
| `position` | `bottom-right` | Screen position |
|
|
| `limit` | 5 | Max visible at once |
|
|
| `expand` | false | Show all without hover |
|
|
|
|
## Gotchas
|
|
|
|
- `importMap.js` is **regenerated on every startup/HMR** — never edit directly; configure component paths in Payload config instead.
|
|
- `layout.tsx` says "DO NOT MODIFY" but is only generated once — safe to edit.
|
|
- Most other `(payload)` files are generated once and safe to modify.
|
|
|
|
## Key Takeaways
|
|
|
|
- Admin Panel = Next.js App Router app nested in `(payload)` route group; REST + GraphQL APIs are just Next.js routes alongside it.
|
|
- White-label ready: every field label, view, and style is swappable via Custom Components.
|
|
- Single auth-enabled Collection gates admin access; RBAC via `access.admin`.
|
|
- `routes` config (root-level) + `admin.routes` (panel-level) give full URL control — but root changes require FS changes too.
|
|
- Timezone config is display-only; DB always UTC; must opt in per Date field.
|
|
- `importMap.js` is the only auto-regenerated file — treat as read-only.
|
|
|
|
## Related
|
|
|
|
- [[wiki/payloadcms/custom-components|Custom Components]]
|
|
- [[wiki/tech-patterns/_index|Tech Patterns — Payload CMS]]
|
|
- [[wiki/architecture/_index|Architecture Patterns]]
|
|
- [[wiki/claude-code/_index|Claude Code — Next.js integration]]
|
|
|
|
---
|
|
|
|
*Source: `raw/admin__overview.md` — https://payloadcms.com/docs/admin/overview*
|