Migrate to typed APIs

Export all five buildersCopy Anchor Link

src/api/builders.ts binds the builders to your plugin. Plugins generated before this change export only buildModule and buildRoute. Add the other three:

import { bindApiPlugin } from "@vitnode/core/api/lib/bind-api-plugin";

import { manifest } from "@/manifest.gen";

const apiBuilders = bindApiPlugin(manifest);

export const buildModule = apiBuilders.buildModule;
export const buildRoute = apiBuilders.buildRoute;
export const buildQueueTask = apiBuilders.buildQueueTask; 
export const defineCacheEntry = apiBuilders.defineCacheEntry; 
export const defineEvent = apiBuilders.defineEvent; 

create-vitnode-app --plugin and vitnode generate write this file with all five.

Move staff permissions to referencesCopy Anchor Link

defineStaffPermissions comes from @vitnode/core/lib/staff-permissions. Create the file, moving the declarations unchanged:

import { defineStaffPermissions } from "@vitnode/core/lib/staff-permissions";

import { manifest } from "@/manifest.gen";

export const staffPermissions = defineStaffPermissions(manifest, {
  admin: { notes: ["can_create"] },
  moderator: { notes: ["can_delete"] },
});

Then replace each guard:

buildRoute({
  adminStaffPermission: { module: "notes", permission: "can_create" },
  // ...
});

import { staffPermissions } from "@/staff-permissions";

buildRoute({
  adminStaffPermission: staffPermissions.admin.notes.canCreate,
  // ...
});

What changes for you:

• Admin and moderator are different types. An admin reference in moderatorStaffPermission, or a moderator one in adminStaffPermission or an AdminCP nav item, is a compile error, even when both declare the same name. Before, both took any { module, permission }, and the wrong kind silently checked the other staff type's grants.
• A reference names its plugin. A guard checks the plugin that declares the permission, not the route's plugin. To guard with core's or another plugin's permission, import that plugin's references, for example coreStaffPermissions from @vitnode/core/lib/core-staff-permissions.
• Generated permissions are a runtime boundary. Content Engine permissions do not exist until the content type is registered, so the compiler cannot check them. contentAdminStaffPermission and contentContainerAdminStaffPermission check them when the module loads instead, and throw for a permission the content type does not generate.

Nothing changes in the database. Stored grants, the AdminCP staff editor and the permission keys (site-notes:notes:can_create) are the same. checkStaffPermission, assertStaffPermission, useAdminPermission and editable pages' permission still take plain { plugin, module, permission } objects; staffPermissionArgs(ref) converts a reference. A guard still decides only who may call a route, not which record they may change. See Permission references.

Give every queue task a schemaCopy Anchor Link

import { buildQueueTask } from "@vitnode/core/api/lib/queue";

const zodPayload = z.object({ noteId: z.number().int().positive() });

export const announceNoteTask = buildQueueTask({
  name: "announce-note",
  handler: async (c, payload) => {
    const { noteId } = zodPayload.parse(payload);
    // ...
  },
});

await c.get("queue").dispatch({
  name: "announce-note",
  payload: { noteId: id },
  pluginId: "site-notes",
});

import { z } from "zod";

import { buildQueueTask } from "@/api/builders";

export const announceNoteTask = buildQueueTask({
  name: "announce-note",
  payload: z.object({ noteId: z.number().int().positive() }),
  handler: async (c, { noteId }) => {
    // ...
  },
});

// where you dispatch it:
await c.get("queue").dispatch(announceNoteTask, { noteId: id });

A task without data takes payload: z.object({}). The task now carries its plugin id, so a dispatch from a listener, a cron job or another plugin's request no longer needs pluginId. buildApiPlugin throws QueueTaskRegistrationError for an entry in queueTasks that is not a task definition, and dispatch throws it for a task that is not registered.

Define events instead of declaring namesCopy Anchor Link

declare module "@vitnode/core/api/models/events" {
  interface VitNodeEvents {
    "site-notes.note.created": { noteId: number; title: string };
  }
}

await c.get("events").emit("site-notes.note.created", { noteId, title });

buildEventListener({ event: "site-notes.note.created", name: "log-new-note", handler });

import { z } from "zod";

import { defineEvent } from "@/api/builders";

export const noteCreatedEvent = defineEvent({
  name: "site-notes.note.created",
  payload: z.object({
    noteId: z.number().int().positive(),
    title: z.string().min(1),
  }),
});

// config.api.ts: buildApiPlugin({ ..., eventDefinitions: [noteCreatedEvent] })
// emit:   await c.get("events").emit(noteCreatedEvent, { noteId, title });
// listen: buildEventListener({ event: noteCreatedEvent, name: "log-new-note", handler });

Keep the event names: listeners in other plugins and external consumers match on them. Delete the declare module file and its side-effect import from config.api.ts. Built-in events lists the definition to import for every core, Content Engine, blog and newsroom event.

What changes at runtime:

• Every emit is validated. A payload the schema rejects now throws EventPayloadValidationError in the emitting request, and nothing is delivered. Before, an emit by name was not validated. Listener and adapter failures are still reported in failures, never thrown.
• Dates travel as ISO strings. An event payload must be JSON, so a date field uses eventDate() from @vitnode/core/api/events/wire: emit an ISO string, and listeners get a Date. Core's only dated payload, moderation.sanction.applied, now takes endsAt as an ISO string; its listeners still receive a Date. Content Engine events emitted with emitContentEvent take Date values and convert them for you.
• Delivery is unchanged. The local adapter runs listeners in the emitting request, once per emit. Events are still not durable and not exactly-once.

Replace string cache keys with entriesCopy Anchor Link

const stats = await c
  .get("cache")
  .remember(`notes:stats:${year}`, 300, async () => await countNotes(c, year));

await c.get("cache").delete(`notes:stats:${year}`);

import { z } from "zod";

import { defineCacheEntry } from "@/api/builders";

export const yearStatsCache = defineCacheEntry({
  name: "year-stats",
  version: 1,
  key: (year: number) => [year],
  schema: z.object({ notes: z.number().int().nonnegative() }),
  ttlSeconds: 300,
});

// read:   await c.get("cache").entry(yearStatsCache, year).remember(loader);
// expire: await c.get("cache").entry(yearStatsCache, year).delete();

Only entry() and flush() stay on c.get("cache"). A stored null is now a hit, where remember used to reload it. Cache API data walks through the full example.

Update generated servicesCopy Anchor Link

Services that vitnode g service and vitnode g resource wrote before this change follow the old stubs. They still compile, but the new shape keeps HTTP out of the service:

In services you have written, replace a thrown HTTPException with a result union or a domain error, and map it to a status in the route. See Add a service.