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.ts
declare 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.ts
import { 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.