Adding an Admin Page
Add a page to /admin safely: authorize with requireAdmin in the loader and every action, copy in a server-only namespace, writes as POST actions.
An admin page is a Void page under apps/web/pages/admin/. The rules are the same ones the kit's pages follow.
Overview pages use AdminPageHeader from @kit/admin/ui: pass the translated title, description and heading testId. It groups the title and description, with a sidebar toggle on mobile only. Keep search and filter controls in a wrapping row inside PageBody; detail pages use <PageHeader displayTrigger="mobile"> for their back link and keep their record actions.
1. Pick or Add a Statement
A statement is resource:action (user:ban). Use one the roles already hold, or add yours in packages/rbac/src/admin-rbac.config.ts and declare it so requireAdmin accepts it by name:
// apps/web/types/admin.d.tsdeclare module '@kit/admin' { interface CustomAdminStatements { 'subscriptions:refund': true; }}A statement the config doesn't define is granted to nobody. See RBAC permissions.
2. Authorize in the Loader
// apps/web/pages/admin/subscriptions.server.tsimport { defineHandler, type InferProps } from 'void';import { requireAdmin } from '#/lib/admin.server.ts';export type Props = InferProps<typeof loader>;export const loader = defineHandler(async (c) => { requireAdmin({ c, statement: 'subscriptions:list' }); return { rows: await listSubscriptions() };});requireAdmin throws the app's 404 (never 403) for anyone not allowed, so the page doesn't reveal it exists. The middleware gate only guides navigation: every loader and every action calls requireAdmin itself, with the statement that action needs.
3. Writes Are POST Actions
export const actions = { refund: defineHandler.withValidator({ body })(async (c, { body }) => { const { admin } = requireAdmin({ c, statement: 'subscriptions:refund' }); // … }),};A GET (and link prefetch) never changes anything. For a destructive action add a step-up code, as ban, role change and impersonation do. After the write has committed, record an audit event with recordAudit and an action of your own (Add Your Own Actions): ids only, never emails, tokens or payloads. The kit.admin.* actions are the kit's; you can't declare one.
4. Copy in a Server-Only Namespace
Admin copy never goes to the browser bundle. Put yours in a <namespace>.server.json under apps/web/messages/<locale>/ (for example adminSubscriptions.server.json), read it in the loader with getServerTranslator({ c, namespace }) and pass the text as props. The kit's own pages use admin.server.json the same way.
5. Check It
- A test that a signed-out request, a normal user and an organization admin get 404 on the page and on each action.
- An entry in
apps/e2e/tests/admin/for what an admin does there.
The sidebar lists the kit's own pages (packages/admin/src/navigation.ts): reach yours by URL, or link to it from your own admin pages.