Editable pages

Declare the pageCopy Anchor Link

Create src/editable-pages/notes-page.ts. It names the page, its zones and who may arrange them:

import { defineEditablePage } from "@vitnode/core/content/editor";

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

export const notesPage = defineEditablePage({
  id: "site-notes:notes",

  permission: {
    plugin: manifest.id,
    module: "widgets",
    permission: "can_edit",
  },

  zones: {
    "before-notes": { allowed: ["core:*"], max: 10 },
    "after-notes": { allowed: ["core:*"], max: 10 },
  },
});

Each zone takes allowed (the allowlist, default "*"), max (default 200, counting widgets, not areas), min, and default, the widgets the zone shows until somebody saves it, written as real stored nodes like { id, type, data }. Without default, a zone starts empty and renders nothing.

The file imports nothing heavy, so the API and the page can both import it.

Register itCopy Anchor Link

In src/config.api.ts, add two keys to the existing buildApiPlugin call: the page in editablePages, and its permission under permissionStaff.moderator. After Plugin page the call looks like this; keep your modules as they are:

import { notesPage } from "./editable-pages/notes-page"; 

export const siteNotesApiPlugin = () =>
  buildApiPlugin({
    manifest,
    modules: [helloModule, notesModule],
    editablePages: [notesPage], 
    permissionStaff: {
      moderator: { widgets: ["can_edit"] },
    },
  });

If your call already has permissionStaff, for example admin: { notes: ["can_create"] } from the Permissions lesson, add the moderator key inside it instead of writing a second permissionStaff.

Then label the permission in src/locales/en.json. Add the two permission keys at the root, next to the site-notes object, and a title inside that object if it has none yet; the AdminCP shows it as the plugin's name. Keep the keys you already have:

{
  "site-notes": {
    "title": "Site Notes"
  },
  "site-notes:widgets": "Widgets",
  "site-notes:widgets:can_edit": "Edit page widgets"
}

Without editablePages, reading the layout answers 404. A page whose permission is missing from permissionStaff.moderator, or a page id registered twice, stops the API at startup with a message naming the fix.

Load the layout in the routeCopy Anchor Link

The loader warms the page's layout and the viewer's permissions, so the zones render on the server. loadPageWidgets needs the query client, which defineRoute from @vitnode/core/tanstack/plugin-routes hands the loader. In src/pages/notes-page.tsx, replace definePluginRoute:

import { defineRoute } from "@vitnode/core/tanstack/plugin-routes"; 
import { loadPageWidgets } from "@vitnode/core/tanstack/widgets"; 

import { notesPage } from "@/editable-pages/notes-page"; 

export const route = defineRoute<NotesPageData>({
  load: async ({ context }) => {
    const [notes] = await Promise.all([
      loadNotes(),
      loadPageWidgets(context.queryClient, notesPage), 
    ]);

    return notes;
  },
});

loadPageWidgets never throws. If the layout cannot be read, the page still renders, without its zones and without Edit widgets, so nobody can save empty zones over the real ones.

Wrap the zones in PageWidgetsCopy Anchor Link

In the same file, wrap the page in PageWidgets and put a PageWidgetsZone wherever a declared zone goes:

import { PageWidgets, PageWidgetsZone } from "@vitnode/core/tanstack/widgets"; 

const NotesPage = ({ loaderData: notes }: PluginRoutePageProps<NotesPageData>) => {
  const t = useTranslations("site-notes.notes");

  return (
    <PageWidgets page={notesPage}>
      <main className="container mx-auto flex max-w-2xl flex-col gap-6 p-4">
        <h1 className="text-2xl font-semibold tracking-tight text-balance">{t("title")}</h1>

        <PageWidgetsZone id="before-notes" />

        {/* the list of notes, unchanged */}

        <PageWidgetsZone id="after-notes" />
      </main>
    </PageWidgets>
  );
};

PageWidgets reads the layout and the permissions the loader warmed, builds the save adapter and keeps the cache up to date after each save. Pass openEditing to honour an ?edit=true link; it only opens the editor for somebody who already may edit.

PageWidgetsZone renders a ContentZone with a flex flex-col gap-6 wrapper and the default widget registry, which always holds core's widgets. If a zone allows your plugin's own widgets, render <ContentZone id="before-notes" registry={blocksRegistry} /> inside PageWidgets instead, with a registry from createBlockRegistry, so the server and the browser render the same widgets.

Grant the permissionCopy Anchor Link

Members with full access hold every permission already. For anyone else, open Staff → Moderators in the AdminCP (/admin/core/staff/moderators), choose Add Moderator, pick a role or a user and choose Add member. Then edit that moderator's permissions, choose Site Notes and tick Edit page widgets under Widgets.