Next.js boilerplate with Admin panel

Three checks, each for a different question

Where	Call	What it stops
src/app/(admin)/layout.tsx	requireRole("admin", returnTo)	A non-admin ever seeing the shell
Every page.tsx	requireRole("admin", "/admin/<path>")	A stale layout: layouts do not re-render on client navigation
Every server action	authorise() in src/lib/admin/actions.ts	Anyone with curl: an action is a public POST endpoint

export default async function AdminReportsPage() {
  await requireRole("admin", "/admin/reports");
  // load data, render
}

The page's call is free: each auth battery wraps its session read in React cache. Pass the page's own path so sign-in brings the admin back to it.

Every export of src/lib/admin/actions.ts starts with authorise(), before it reads a form field. It runs requireRole("admin"), then re-reads the admin from the provider, because a role removed a minute ago can still sit in a cached cookie (Better Auth, 5 minutes) or an unexpired token (Clerk, Supabase). The one exception is stopImpersonationAction: the impersonated session is not an admin session, so it checks adminProvider.getImpersonation() instead.

A route handler under src/app/api/admin/** uses requireApiRole("admin") (401 or 403, never a redirect) and catches with authErrorResponse.

Never:

• rely on the proxy: /admin/:path* is in its matcher so signed-out visitors bounce early, but it has no role check worth trusting;
• compare strings (user.role === "admin" misses Clerk's owner): use requireRole, or navItemsFor for what the UI shows;
• move a page out of src/app/(admin)/admin/: it loses the shell and the layout's check, and nothing warns you;
• render the shell for a refused user: requireRole answers with a 404 or the auth battery's no-access page, and the chrome would tell an outsider the page exists.

Pages load, components render

A page is a Server Component. It calls the read helpers (listUsers, getUser, getUserStats from @/lib/admin/users, listAuditEntries from @/lib/admin/audit) and passes results down. Load independent data with Promise.all. A slow section goes in its own async component inside <Suspense> with a skeleton, as /admin does for its counts.

Components under src/components/admin/** take props. Two kinds load their own data because a slot cannot pass them any: ImpersonationBanner (the app-banner fill) and the billing summary (AdminBillingStats, AdminBillingCard). Do not add a third without the same reason.

Keep data on the server

• Modules in src/lib/admin/ that reach a provider open with import "server-only": users.ts, audit.ts, user-store.ts, provider.ts, audit-store.ts. Client components import only the pure ones (types.ts, policy.ts, format.ts, query.ts, cursor.ts) and the "use server" actions.
• Pick fields for client components: UserActions gets { id, name, email, role, banned }, never a database row.
• Never send a session token to the browser. The page sends a session id; findSessionToken turns it into a token on the server.
• Filters and cursors live in the URL, parsed by parseUserQuery and parseAuditQuery. A value that does not parse means "no filter", never an error page.

Look like the rest of the app

Use the kit (@/components/ui/*), PageHeader and EmptyState from @/components/app/*, and token classes (bg-surface-card, text-muted, border-hairline). No palette classes, no hex, no dark: for colour: the panel must read well in every design, light and dark.

The panel is written once against three ports in src/lib/admin/contract.ts. Only the ports differ between auth providers and ORMs:

Port	File	Job
AdminUserStore	src/lib/admin/user-store.ts	Reads: list, get, sessions, counts
AdminProvider	src/lib/admin/provider.ts	Writes: ban, unban, role, sessions, impersonation
AuditStore	src/lib/admin/audit-store.ts	The trail: audit_log, or server logs without a database

Pages, components and actions import the ports. They never import better-auth, @clerk/nextjs/server, @supabase/* or @/db directly. A port that grows a method grows it in every variant of that file, or some repos stop compiling.

The order inside every action

src/lib/admin/actions.ts does these seven steps, in this order. A new action does the same (the /add-admin-action skill walks through it):

1. authorise(): the role check plus a fresh read of the admin.
2. Parse the form with zod. Return fieldErrors from z.flattenError.
3. Re-read the target with adminUserStore.get(id). The page may be stale.
4. Run the rule from src/lib/admin/policy.ts (no self-ban, no demoting the last admin, no impersonating an admin). Rules are pure and unit-tested.
5. Call the provider inside try/catch, and turn errors into one sentence with adminProvider.errorMessage().
6. recordAdminAction() from src/lib/admin/audit.ts.
7. Return AdminActionState; done() revalidates /admin.

redirect() and requireRole() throw to work. Keep them outside try.

Audit entries

• Action names are past tense and namespaced: admin.user.banned, admin.user.role_changed, admin.impersonation.started. Add a label for a new one in ACTION_LABELS in src/lib/admin/format.ts.
• recordAdminAction adds both emails, the IP and the user agent. Put only what explains the change in metadata: the reason, the duration, from and to. Never a password, a token or a session token.
• The provider write and the audit insert are different systems, so the write goes first. If the insert fails, the action still reports success, says the audit entry failed, and the entry is logged as JSON. Do not "fix" this by auditing first: the log would then describe changes that never happened.
• The trail is append-only. No code updates or deletes audit_log rows.

Provider facts that shape the code

• Better Auth: writes go through auth.api.* with the request headers, so Better Auth checks the caller too. A ban deletes sessions, but a browser's 5 minute cookie cache can outlive it. Reads use the ORM, because auth.api.listUsers search is case-sensitive. An impersonation session is read-only at /api/auth too (the endpoint guard in src/lib/auth/auth.ts), so do not add an allowlisted endpoint for convenience.
• Clerk: bans have no reason or expiry, so both live in privateMetadata.ban and admin:unban-expired lifts timed bans. Roles live in publicMetadata.role. Impersonation uses actor tokens and signs the admin out; the free plan allows 5 a month. Clerk documents no lock on account changes for an actor session, so the app's read-only settings are the lock.
• Supabase Auth: reads go through the service-role SQL functions in supabase/migrations/*_admin_panel.sql. An issued access token survives a ban until it expires. Impersonation is built from generateLink plus a server-side verifyOtp, signs the admin out, and confirms an unconfirmed email. Its session gets not_after (admin_limit_session) so Supabase refuses to refresh it past the limit, and Stop deletes it by id. GoTrue has no read-only session: never tell an operator more than that.

Client components

Admin dialogs are client components that call the actions through useAdminAction (useActionState plus a toast). They receive plain props: ids, names, emails, flags. Never pass a provider object, a database row or a session into one; everything passed is readable in the page source.