Write a console plugin
Add a feature of your own as a local plugin: a workspace sidebar entry, a page and a dashboard card that an administrator can switch on and off.
A local plugin wires a feature you wrote into the console without editing the shells. This guide builds one called notes: an entry in the workspace sidebar, a page at /app/notes and a card on the /app dashboard. The same steps apply to the admin console with the admin.nav slot. For how the kernel works, see Plugins.
Before you begin
- A project that runs locally with
pnpm dev. - An administrator account with
config.readandconfig.write, to open Settings → Plugins. - A plugin id: a lower-case slug such as
notes, unique among the plugins insrc/plugins/installed.ts. - The pass/fail set of
pnpm validate:allrecorded before you start, so you can confirm afterwards that no passing check now fails.
Build the plugin
Write the manifest
The manifest is pure data. kind: "local" marks a plugin that belongs to this project. routes lists the path prefixes the plugin owns, without the locale prefix.
import { defineManifest } from "../kernel/types";
export const notesManifest = defineManifest({
id: "notes",
version: "0.1.0",
kind: "local",
routes: ["/app/notes"],
});Add the copy
Navigation labels are dictionary keys. Add notes to the appConsole namespace in both src/i18n/locales/en/messages.ts and src/i18n/locales/zh/messages.ts. A key present in one locale only fails pnpm validate:app-i18n.
Add the page
Create the route under the locale-aware tree. active must be the id of the app.nav entry you contribute in the next step.
import { createFileRoute } from "@tanstack/react-router";
import { useAuth } from "@/components/auth/auth-state";
import { AppConsoleLayout } from "@/components/layout/app-console-sidebar";
import { useI18n } from "@/i18n/use-i18n";
export const Route = createFileRoute("/{-$locale}/app/notes/")({
component: NotesPage,
});
function NotesPage() {
const { locale, t } = useI18n();
const { user } = useAuth();
return (
<AppConsoleLayout active="notes" locale={locale} user={user}>
<h1 className="text-lg font-medium">{t("appConsole.notes")}</h1>
</AppConsoleLayout>
);
}The page needs no guard of its own. The /app layout protects it, and the same layout returns not found for the route while the plugin is switched off. Load data through a server function that calls requireCurrentUserId(), as described in Add a page.
Write the dashboard card
A dashboard card is a component that receives the current locale.
import { Surface, SurfaceContent } from "@/components/motion/surface";
import { getDictionary, type Locale, localizedPath } from "@/i18n/messages";
export function NotesCard({ locale }: { locale: Locale }) {
const { t } = getDictionary(locale);
return (
<Surface>
<SurfaceContent>
<a href={localizedPath("/app/notes", locale)}>{t("appConsole.notes")}</a>
</SurfaceContent>
</Surface>
);
}Build it from @workspace/beui, src/components/motion and Tailwind utilities. A file under src/plugins that imports src/components/ui or reads process.env fails pnpm validate:plugins.
Contribute to the slots
import { NotebookPen } from "lucide-react";
import { definePlugin } from "../kernel/types";
import { notesManifest } from "./manifest";
import { NotesCard } from "./notes-card";
export const notesPlugin = definePlugin({
manifest: notesManifest,
contributes: {
"app.nav": [
{
id: "notes",
icon: NotebookPen,
labelKey: "appConsole.notes",
path: "/app/notes",
section: "product",
order: 50,
},
],
"app.dashboard.cards": [{ id: "notes.summary", order: 10, component: NotesCard }],
},
});The foundation's own product entries use orders 0 to 40, so 50 places the entry after them. Each field is typed in src/plugins/slots.ts; see Client slots and server slots.
Register it
Add the plugin to the installed list. Keep it outside every // @module: region. Those regions belong to the shipped modules, and a local plugin inside one fails the validator.
import { notesPlugin } from "./notes/plugin";
export const installedPlugins: readonly Plugin[] = [
foundationPlugin,
// … the regions of the shipped modules …
notesPlugin,
];Run pnpm dev once so src/routeTree.gen.ts picks up the new route file.
Add server-side behaviour
A plugin that serves HTTP endpoints or reacts to paid orders adds a plugin.server.ts with defineServerPlugin, contributes to api.routes or billing.fulfilment, and is listed in src/plugins/installed.server.ts as well. That file is also imported by the agent service, so nothing reachable from it may import React, icons or @/ aliases.
Server functions of the plugin call requirePluginEnabled("notes") from src/server/plugins/state.ts after their auth guard, so they reject calls while the plugin is off. Endpoints contributed to api.routes need no such call, because the host returns 404 for a switched-off plugin. See Fulfil paid orders for the billing slot.
Verify
pnpm typecheckpasses. A wrong slot name or a missing field in a contribution is a type error.pnpm validate:pluginspasses. It checks that the registry builds, that the nav entry reaches a route file, that the entry sits under a prefix in the plugin'sroutes, and that the page'sactivevalue is a contributedapp.navid.- Open
/app: the Notes entry is in the sidebar and the card is above the account summary. Open/app/notes. - Open Settings → Plugins (
/admin/plugins). Thenotesrow lists its workspace entry and its route. Switch it off. - Reload
/app: the entry and the card are gone, and/app/notesshows the not-found page. Switch it back on and both return. pnpm validate:allturns no check red against the set you recorded.
Troubleshooting
The app fails to start with duplicate_slot_key
Another plugin already contributes that key to the slot: an app.nav entry with the same id, or an admin.nav entry with the same to. The message names the slot, the key and both plugins.
The app fails to start with duplicate_plugin_route
Two manifests claim the same prefix in routes. A prefix has one owner; nest the new route under a prefix of its own.
pnpm validate:plugins reports module-entries-sit-in-their-own-routes
A nav entry of the plugin points outside the prefixes in its manifest. Add the prefix to routes; otherwise switching the plugin off would hide the entry but leave the page reachable.
Next steps
Plugins
How the plugin kernel works: what a plugin is, the client and server slots it contributes to, how plugins are installed at build time and switched on and off at runtime.
Templates and derived products
How a module differs from a template inside the repository, what the business templates are, and how a product of your own is built on the foundation by adding one plugin.