Kernlift

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.read and config.write, to open Settings → Plugins.
  • A plugin id: a lower-case slug such as notes, unique among the plugins in src/plugins/installed.ts.
  • The pass/fail set of pnpm validate:all recorded 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.

src/plugins/notes/manifest.ts
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.

src/routes/{-$locale}/app/notes/index.tsx
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.

src/plugins/notes/notes-card.tsx
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

src/plugins/notes/plugin.ts
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.

src/plugins/installed.ts
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

  1. pnpm typecheck passes. A wrong slot name or a missing field in a contribution is a type error.
  2. pnpm validate:plugins passes. It checks that the registry builds, that the nav entry reaches a route file, that the entry sits under a prefix in the plugin's routes, and that the page's active value is a contributed app.nav id.
  3. Open /app: the Notes entry is in the sidebar and the card is above the account summary. Open /app/notes.
  4. Open Settings → Plugins (/admin/plugins). The notes row lists its workspace entry and its route. Switch it off.
  5. Reload /app: the entry and the card are gone, and /app/notes shows the not-found page. Switch it back on and both return.
  6. pnpm validate:all turns 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