Kernlift

Add an admin or workspace page

Add one screen under /admin or /app with a guarded server function, copy in both locales and a navigation entry.

This guide adds a single screen: an operator page under /admin or a customer page under /app. The layout already protects it, so you add a route file, a server function that checks who is calling, copy in two languages and one navigation entry. For a whole feature with its own tables, build a module. See Build a module.

Before you begin

  • A project that runs with pnpm dev, and an administrator account. See Run the admin console.
  • The path (/admin/<name> or /app/<name>), what the page reads and what it writes.
  • For an admin page: the permission key that gates it. Reuse an existing key from the catalog at /admin/permissions when one fits.
  • If you work with a coding agent, the new-page skill carries the same steps. See Use agent skills.

Understand what the layout gives you

AreaLayout routeWhat it does before your page loads
/admin/*src/routes/{-$locale}/admin.tsxRequires a session and the admin.access permission. No session redirects to /system/session-expired; no permission to /system/permission-denied
/app/*src/routes/{-$locale}/app.tsxRequires a session. No session redirects to /system/session-expired; a banned account to /system/permission-denied

Both layouts also return not found for a page that belongs to a plugin which is switched off, and pass the signed-in user's permissions to the page through AuthProvider. A new file under either directory is protected without any code of its own.

The layout protects pages. It does not protect data: a server function is an HTTP endpoint anyone can call, so each server function must check the caller.

Add the page

Write the server function

Add it to the matching file in src/server/functions/, or a new file there. Validate input with zod, resolve the caller first, then delegate to a service.

src/server/functions/reports.ts
import { createServerFn } from "@tanstack/react-start";
import { requireAdminPermission } from "./admin-permissions";
import { requireCurrentUserId } from "./session";

// Admin: gate on a permission.
export const getAdminReports = createServerFn({ method: "GET" }).handler(async () => {
  await requireAdminPermission("reports.read");
  return listReports();
});

// Workspace: bind to the signed-in user.
export const getMyReports = createServerFn({ method: "GET" }).handler(async () => {
  const userId = await requireCurrentUserId();
  return listReportsForUser(userId);
});

requireAdminPermission() throws Permission denied: <key> for a caller without the permission. requireCurrentUserId() rejects a caller with no session or a banned account. There is no fallback identity. Database access belongs in a repository under src/server/db/repositories/, called from a service.

Add the copy to both locales

Add a namespace with the same keys to src/i18n/locales/en/messages.ts and src/i18n/locales/zh/messages.ts, and a label for the navigation entry under shell.nav (admin) or appConsole (workspace). See Add and change copy.

Create the route file

For an admin page, copy the shape of src/routes/{-$locale}/admin/rate-limits.tsx:

src/routes/{-$locale}/admin/reports.tsx
import { createFileRoute } from "@tanstack/react-router";
import { AdminRecords } from "@/components/admin/admin-records";
import { adminRouteFeedback } from "@/components/admin/admin-route-feedback";
import { AppShell } from "@/components/layout/app-shell";
import { getMessageNamespace, normalizeLocale } from "@/i18n/messages";
import { getAdminReports } from "@/server/functions/reports";

export const Route = createFileRoute("/{-$locale}/admin/reports")({
  ...adminRouteFeedback,
  loader: () => getAdminReports(),
  component: AdminReportsPage,
});

function AdminReportsPage() {
  const rows = Route.useLoaderData();
  const locale = normalizeLocale(Route.useParams().locale);
  const copy = getMessageNamespace(locale, "adminReportsCopy");
  return (
    <AppShell activeNav="Reports" currentPage={copy.currentPage} locale={locale} mode="admin">
      <AdminRecords
        columns={[{ key: "name", label: copy.name, render: (row) => row.name }]}
        emptyLabel={copy.empty}
        rowKey={(row) => row.id}
        rows={rows}
      />
    </AppShell>
  );
}

adminRouteFeedback supplies the pending and error components. Spread it into every admin route.

For a workspace page, copy src/routes/{-$locale}/app/tickets/index.tsx. That page renders inside AppConsoleLayout from @/components/layout/app-console-sidebar, reads copy with useI18n(), and passes the id of its navigation entry as active.

A list page that has a detail child returns <Outlet /> when the path goes deeper, as src/routes/{-$locale}/admin/orders.tsx does.

Build the body from the design system

Compose the admin patterns (AdminRecords, AdminMetrics, AdminPanel, the Config* layout, useAdminSave) and components from src/components/motion. Do not import src/components/ui, and do not add a <main>, because the shell renders it. See Use the design system.

For a page that saves, call useAdminSave("<key>.write"). Disable the form when allowed is false, and check the same permission again in the server function that writes.

Add the navigation entry

Sidebar entries are plugin contributions. For a page that is part of your product, add it to the foundation plugin in src/plugins/foundation/plugin.ts.

An admin entry goes in the adminNav array:

src/plugins/foundation/plugin.ts
{
  ...operations,
  label: "Reports",
  labelKey: "shell.nav.reports",
  to: "/admin/reports",
  icon: ListChecks,
  permission: "reports.read",
  order: 650,
},

The group constants at the top of the file (overview, operations, commerce, platform, security, settings) set the sidebar section. order sets the entry's position. Foundation entries step by 100, so yours fits between two of them. permission is required, and the sidebar hides the entry from anyone who lacks it.

A workspace entry goes in the app.nav list of the same plugin:

src/plugins/foundation/plugin.ts
{
  id: "reports",
  icon: ListTodo,
  labelKey: "appConsole.reports",
  path: "/app/reports",
  section: "product",
  order: 35,
},

section is product or account. The page passes the same id as active to AppConsoleLayout.

To ship the page as something that can be switched off at /admin/plugins, give it its own plugin. See Console plugins.

Grant a new permission

Skip this if you reused an existing key. For a new key, add a row to superAdminPermissionTemplates in src/server/services/super-admin-bootstrap.service.ts, then run:

pnpm db:bootstrap-super-admin

The script upserts every permission and grants them all to the Super Admin role. Grant the key to other roles at /admin/roles. See Manage users, roles and permissions.

Regenerate the route tree

pnpm dev

Starting the dev server rewrites src/routeTree.gen.ts with the new route. Then run pnpm typecheck.

Verify

pnpm typecheck
pnpm validate:auth-boundary
pnpm validate:plugins
pnpm validate:beui-console
pnpm validate:route-i18n
pnpm validate:app-i18n

What these catch on a new page:

ValidatorFails when
pnpm validate:auth-boundaryAn exported server function neither resolves identity nor checks a permission. A deliberately public function must be listed with its reason in publicServerFunctions in scripts/validate/auth-boundary.ts
pnpm validate:pluginsA navigation entry points at no route file, an admin entry has no permission, or a workspace page passes an active id that no app.nav entry declares
pnpm validate:beui-consoleThe page reaches src/components/ui, renders outside the shells, or adds its own <main>
pnpm validate:route-i18nThe route file is not under src/routes/{-$locale}/

Then check in the browser:

  • Open the page at its English path and under /zh, in the light and the dark theme.
  • Sign in as a user without the permission. The sidebar entry is gone, and opening the URL directly shows the route's error state because the loader's server function rejects the call.
  • Sign out and open the URL. You are redirected to /system/session-expired.

Next steps