Skip to content

Shaping the admin your project ships

The admin is a registry of surfaces grouped into 25 areas; config denies areas or surfaces at build time and a per-site settings row does it at runtime.

Every admin route is a declared entry in one typed registry — an id, a feature area, a URL pattern, a minimum role and a lazy component loader — not a page in your app. That is what makes the admin subtractable: you never delete a route, you deny an id.

Areas and surfaces are two different granularities

An area is the feature taxonomy: 25 of them, from dashboard and contentTree through audiences, experiments and changesets to settings and account. A surface is one route inside an area — a list, a new form and a detail view are three surfaces, each its own lazily loaded chunk. Sixty-three make up the shipped admin; thirty-eight appear in the sidebar across six sections (five labelled, plus an unlabelled overview group), and the other twenty-five — the same count as the areas, coincidentally — are unlisted surfaces: detail routes, create forms, utilities like media.upload and search.index, and the account password screen.

Config is the ceiling

The admin block is a denylist that defaults to on. An absent block, an area you did not mention, a surface you did not list: all enabled. Only an explicit false or an explicit id removes anything. Deny an area and everything in it goes; deny a surface id and one route goes while its area stays.

kywi.config.tsts
admin: {
  // enabled: false would leave an API-only host with no admin at all
  features: {
    experiments: false,   // the whole area, nav rows included
    translations: false,
  },
  disableSurfaces: ['media.upload'],  // one route, area otherwise intact
},

A denied surface is not a 404. Core answers a genuinely unknown admin path with one, but a known route held off by the ceiling renders the shell's own "disabled" message — so a link into it from a bookmark or an old doc explains itself instead of looking broken.

Runtime flags are per site, and softer

The second lever is a single kywi_site_settings row keyed admin.features, holding a flat map of area or surface id to boolean. It is per site rather than per deployment, so one site can hide Experiments while another keeps it — see One config, several sites. Like the config block it is active-by-default: no row, or no entry, means enabled.

The two compose as an AND, with config as the hard floor: a surface renders only if the config ceiling allows it, the runtime flag does not deny it, and the signed-in user clears its minRole — see Roles and the capability matrix for the third term.

Your layers reach the admin, minus their templates

The admin route gets the same kywi.layers.ts registry the public route does, so the layout editor can render your custom modules — but not your templates: core strips the templates key from every layer first. The admin app is a client component, while hydrateLayout and shell are server-only, and either one crossing that boundary throws and takes down the whole admin, not just one surface. The strip removes the whole key rather than a list of known names, so a new template slot cannot reintroduce the failure; site and theme keys survive it.