Admin

A generic admin area. It owns no domain features: it provides the shell (an admin layout with a sidebar), a guarded dashboard page and the registries other modules plug into. Domain admin UIs (forms, events, OAuth applications, users, ...) stay in their own modules and register here.

Quick setup

export default defineNuxtConfig({
  modules: ['@nuxt/ui', '@frigear-nu/authorization', '@frigear-nu/admin'],
  admin: {
    settings: {
      roles: ['admin', 'manager'],
    },
  },
})

Options

All options live under admin.settings.

Behaviour of the generated route rules:

• Guard: { roles } on <base>/**, only when @frigear-nu/authorization is installed. Without it nothing guards the pages on the client and a warning is logged. An explicit rule of yours wins. API routes are guarded by the modules that own them.
• Layout: { appLayout: 'admin' } on <base> and <base>/** (the dashboard at base itself is not matched by the wildcard, so it gets its own rule). A rule of yours wins.
• Locales: with @nuxtjs/i18n the rules are repeated for each /<locale> prefix.
• Account menu: unless dashboard or roles is false, an "Admin" entry is added to the account.dropdown menu, shown only to users holding one of the roles.

Server

None. The module registers no server routes.

App

Navigation groups

The sidebar is three groups, each read from its own menu path. ADMIN_NAV_GROUPS (from @frigear-nu/admin/utils) lists them in display order:

The layout reads all three in one useMenu('admin.nav.*') call and renders them as labelled sections (Overview has no label; Manage and Settings do). A new feature goes into an existing group; a new group needs a reason (see UX patterns).

Registries

Modules never import the admin module at runtime. The documented way to add a sidebar entry is a runtime menu source: a module registers a runtime/menus.ts file, and that file pushes items into the group's menu path with extendMenuItem. It works whether or not @frigear-nu/admin is installed, because the sidebar is just a menu.

// module.ts
import { addOptionalMenuSource } from '@frigear-nu/module-kit/utils'

addOptionalMenuSource(nuxt, { file: resolver.resolve('./runtime/menus'), menu: 'admin' })

// runtime/menus.ts
import { defineMenuItem, defineMenuSource, extendMenuItem } from '@frigear-nu/menu/utils'

export default defineMenuSource(() => {
  const config = useRuntimeConfig().public.forms

  // Manage group (the root of `admin.nav`)
  extendMenuItem('admin.nav', defineMenuItem({
    id: 'forms-admin',
    label: 'Forms',
    labelKey: 'forms.menu.admin.label',
    icon: 'i-lucide-clipboard-list',
    to: config.pages.admin,
    order: 30,
  }))

  // Settings group
  extendMenuItem('admin.nav.settings', defineMenuItem({
    id: 'forms-settings',
    label: 'Form settings',
    icon: 'i-lucide-settings-2',
    to: '/admin/forms/settings',
  }))
})

For static entries known at build time there is sugar over extendMenu, plus the dashboard helpers. They come from @frigear-nu/admin/utils:

import { extendAdminNav, extendAdminDashboard, adminRoute } from '@frigear-nu/admin/utils'

extendAdminNav(nuxt, { label: 'Forms', to: adminRoute(nuxt, 'forms'), icon: 'i-lucide-clipboard-list', order: 20 })
extendAdminNav(nuxt, { label: 'OAuth applications', to: adminRoute(nuxt, 'oauth'), icon: 'i-lucide-key-round' }, 'settings')
extendAdminDashboard(nuxt, { component: resolver.resolve('./runtime/app/widgets/Submissions.vue'), order: 10 })
extendAdminDashboard(nuxt, { component: resolver.resolve('./runtime/app/widgets/SubmissionCount.vue'), order: 10 }, 'top')

A module can also call extendMenu / extendWidgets directly, without depending on this package.

Dashboard areas

The dashboard is three widget areas, so modules fill it without the admin module knowing them:

Widgets load their own data (useLazyFetch, so the page doesn't wait) and receive no context. Without widgets in any of the areas, the dashboard shows a shortcut card for every entry of the Manage and Settings groups.

Runtime config

runtimeConfig.public.admin holds the resolved values:

type PublicModuleOptions = {
  base: string
  dashboard?: string // undefined when the dashboard is off
}

Layout and page

The admin layout is a Nuxt UI dashboard shell:

• Sidebar: the brand, the ⌘K search button, the grouped navigation (Overview, Manage, Settings) and, in the footer, a "Back to the site" link and the account menu (AccountMenu from Account, when installed: it shows the signed-in user and a colour-mode switch under Appearance).
• Navbar: the sidebar collapse button, the title of the current section and, with more than one locale, LanguageSelect. There is no colour-mode button in the navbar: appearance lives in the account menu.
• ⌘K: the palette has one group per navigation group, listing the same entries, so everything in the sidebar is searchable. AccountMenu and LanguageSelect are resolved by name, so a host's own versions win and neither is required.
• Links are built with useNavLinks, so they keep the visitor's locale prefix and the active entry is highlighted.

Components

The admin pages are built from the shared components of @frigear-nu/ui: PageHeading, PageToolbar, TableCard, RowMenu, SectionCard, DescriptionList, StatCard, ListCard and FormSlideover. They are registered globally by that module, which this module now depends on. Use them directly; see UX patterns for how a list, a detail page and a form are put together.

Modules that ship admin pages declare @frigear-nu/admin as an optional module dependency and @frigear-nu/ui as a dependency; a host that enables those pages installs both.

Page conventions

Every admin page follows UX patterns. In short:

• Lists: PageHeading with the primary action, PageToolbar for search past about eight rows, UTable in TableCard with clickable rows and a RowMenu in the last column.
• Detail pages: PageHeading with a breadcrumb back to the list, then SectionCards; extensible tabs are WidgetTabs, the page's own sections are PageTabs.
• Create and edit: FormSlideover opened with useOverlay(), behind a use<Entity>Actions() composable.
• Destructive actions: useConfirmDialog({ destructive: true }), saying what else is affected.
• Feedback: a toast with the record's name; errors through useErrorToast.
• Text: useModuleT with an English default; buttons name the object ("Add user", not "Add").

Translations

Namespace admin, shipped in English and Danish.