Extension points

Your module has a Billing page. It should appear in the account menu, put a widget on the admin dashboard and offer a tool to AI agents, without you editing the Account, Admin or MCP modules. After this page you can decide which extension point to use for each of those, and where its full reference lives.

Which one do I use?

Terms

• Extension point. A place where one module adds things to another without importing it, either a registry or a hook.
• Registry. A build-time list that modules add entries to, such as menus, widgets, tabs, permissions, roles, scopes and Model Context Protocol (MCP) tools.
• Hook. A runtime hook (Nitro or app) that a module calls and that listeners in the host app or other modules answer.
• Widget area. A named slot where the Widget module renders the components modules add.

How it works

Extension points come in two kinds:

Registration order between modules never matters: items are merged after modules:done.

Registries

Most registries are built on defineVirtualRegistry from @frigear-nu/module-kit/utils.

1. The module that owns the registry calls it from its setup().
2. Other modules add entries during their own setup(), through the owner's helper.
3. Once every module is done, the entries are bundled into one virtual module that the runtime imports.

There is no scanning at run time, which keeps it working on Cloudflare Workers.

Registries and menus has the signature and options of defineVirtualRegistry, including its app and server targets.

Hooks: ask the host app

A hook is a question a module asks and the host app answers. Access control has two Nitro hooks, both answered by your host app (or another module), and three app hooks that filter what the interface shows:

authorization:before is the single override. Results are collected across listeners: any deny() or a listener that throws denies; otherwise any allow() allows. It runs after the credential checks, so it can never give a token a permission it was not issued, nor a token a sessionOnly permission. A listener identifies the caller from ctx.user, never from the session on ctx.event. The filter hooks only hide things; the server still checks.

Access control explains both Nitro hooks. At build time, auth:access-compiled hands the compiled permissions, roles and scopes to any module that wants to read them, for example to list them in documentation or an admin page.

Menus

Menu holds named menus, such as main, dashboard and account. A menu path is split on its first dot: dashboard.more is group more of menu dashboard. Items from Nuxt Content, from modules and from runtime sources are merged and sorted by order.

An item may name a permission. The item is hidden for a viewer who lacks it, and the menu is resolved again on sign-in and sign-out. The route behind the item checks the permission itself.

A module adds static items at build time:

import { extendMenu } from '@frigear-nu/menu/utils'

extendMenu(nuxt, 'dashboard.more', [
  { label: 'Billing', description: 'Manage your subscription', to: '/billing' },
])

Dynamic items come from a runtime source file. A module that must work without Menu registers its source with addOptionalMenuSource from @frigear-nu/module-kit/utils. It does nothing when Menu is not installed.

Widget areas and tabs

Widget offers two registries with the same ordering and gating. A widget or tab may name a permission; widgets:filter and tabs:filter hide it from viewers who lack it.

• Widgets fill a named widget area. The host app renders <WidgetArea name="admin.dashboard"> wherever it likes. Modules add components with extendWidgets.
• Tabs fill a detail page. <WidgetTabs name="admin.users"> renders every registered tab, with the active tab in ?tab=.

import { extendWidgets, extendTabs } from '@frigear-nu/widget/utils'

extendWidgets(nuxt, 'admin.dashboard', { component: resolver.resolve('./runtime/app/widgets/NewMembers.vue'), order: 10 })
extendTabs(nuxt, 'admin.users', { id: 'payments', component: resolver.resolve('./runtime/app/tabs/Payments.vue'), label: 'Payments' })

An entry registered again under the same id replaces the earlier one. That is how a host app overrides a module's widget.

Admin navigation and dashboard

Admin draws the admin area entirely from the two registries above. The sidebar is three menu groups:

The dashboard is three widget areas:

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

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

New features go into one of the existing groups. A module can also call extendMenu and extendWidgets directly, without depending on Admin. See Layouts and navigation.

Account menu and overview

Account uses the same registries for the account pages:

• The account menu is the account navigation and the overview's shortcuts.
• account.dropdown is the account menu in the header.
• A module adds an account page by registering the route and a menu item. It never draws its own account navigation.
• The account.overview widget area fills the overview page. Its widgets receive the session user as a prop.
• order places a page between others. Membership sits at 15, Tickets at 40 and Applications at 50.

MCP tools

MCP serves one Model Context Protocol endpoint for everybody. A module adds tools from its setup() with addMcpDefinitions. It defines them with defineScopedMcpTool, defineScopedMcpResource and defineScopedMcpPrompt:

addPermission(nuxt, { name: 'notes:read', label: 'Read your notes', implicit: true })
if (options.settings?.mcp === true) addMcpDefinitions(nuxt, resolver.resolve('./runtime/server/mcp'))

• Every definition declares the permission it needs.
• A tool is listed and callable only when allows(event, permission) is true for the caller's credential, so a token that holds only tickets:read never sees an admin tool.
• A tool takes the user from ctx.user, never as an argument.
• ctx.can(permission, record?) asks a further permission for the same caller, such as an opt-in *:pii.
• Exposing tools is opt-in per module, through settings.mcp.

Auth extension points

@frigear-nu/auth/utils offers these build-time registries. Any module may call them from its setup():

Users registers the user store. That is why Auth works without depending on it. Authorization registers the role provider in the same way. Access control shows each one in use, and how the host's config merges with what modules register.

Bootstrap providers

Some pages show several modules' data for the signed-in user, such as the account pages. Without help they make one request per module. registerBootstrapProvider adds a module's piece to the single GET /api/auth/bootstrap?scope=<scope> request of that area. See Module Kit.

Common mistakes

Next steps

• Add an admin page – put the registries to work in a real page.
• Database extensions – use the one extension point that changes the schema.
• Writing a module – start a module that adds to others.